docs: i2c: convert to ReST and add to driver-api bookset

Convert each file at I2C subsystem, renaming them to .rst and adding to the driver-api book. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Wolfram Sang <wsa@the-dreams.de> Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: i2c: convert to ReST and add to driver-api bookset
Convert each file at I2C subsystem, renaming them to .rst and adding to the driver-api book. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Wolfram Sang <wsa@the-dreams.de> Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
ccf988b6 · Mauro Carvalho Chehab · Jonathan Corbet · 09f4c750 · ccf988b6 · ccf988b6
Commit ccf988b6 authored Jul 26, 2019 by Mauro Carvalho Chehab Committed by Jonathan Corbet Jul 31, 2019
80 changed files
--- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
@@ -42,7 +42,7 @@ Optional properties:
  This means that no unrelated I2C transactions are allowed on the parent I2C
  adapter for the complete multiplexed I2C transaction.
  The properties of mux-locked and parent-locked multiplexers are discussed
-  in more detail in Documentation/i2c/i2c-topology.
+  in more detail in Documentation/i2c/i2c-topology.rst.
 For each i2c child node, an I2C child bus will be created. They will
 be numbered based on their order in the device tree.

--- a/Documentation/driver-api/ipmb.rst
+++ b/Documentation/driver-api/ipmb.rst
@@ -83,7 +83,7 @@ Instantiate the device
 ----------------------
 After loading the driver, you can instantiate the device as
-described in 'Documentation/i2c/instantiating-devices'.
+described in 'Documentation/i2c/instantiating-devices.rst'.
 If you have multiple BMCs, each connected to your Satellite MC via
 a different I2C bus, you can instantiate a device for each of
 those BMCs.

--- a/Documentation/hwmon/adm1021.rst
+++ b/Documentation/hwmon/adm1021.rst
@@ -142,7 +142,7 @@ loading the adm1021 module, then things are good.
 If nothing happens when loading the adm1021 module, and you are certain
 that your specific Xeon processor model includes compatible sensors, you
 will have to explicitly instantiate the sensor chips from user-space. See
-method 4 in Documentation/i2c/instantiating-devices. Possible slave
+method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave
 addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that
 only temp2 will be correct and temp1 will have to be ignored.

--- a/Documentation/hwmon/adm1275.rst
+++ b/Documentation/hwmon/adm1275.rst
@@ -75,7 +75,7 @@ Usage Notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 The ADM1075, unlike many other PMBus devices, does not support internal voltage

--- a/Documentation/hwmon/hih6130.rst
+++ b/Documentation/hwmon/hih6130.rst
@@ -27,7 +27,7 @@ The devices communicate with the I2C protocol. All sensors are set to the same
 I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27)
 can be used in the board setup code.
-Please see Documentation/i2c/instantiating-devices for details on how to
+Please see Documentation/i2c/instantiating-devices.rst for details on how to
 instantiate I2C devices.
 sysfs-Interface

--- a/Documentation/hwmon/ibm-cffps.rst
+++ b/Documentation/hwmon/ibm-cffps.rst
@@ -17,7 +17,7 @@ Usage Notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 Sysfs entries

--- a/Documentation/hwmon/lm25066.rst
+++ b/Documentation/hwmon/lm25066.rst
@@ -76,7 +76,7 @@ Usage Notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.

--- a/Documentation/hwmon/max16064.rst
+++ b/Documentation/hwmon/max16064.rst
@@ -28,7 +28,7 @@ Usage Notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.

--- a/Documentation/hwmon/max16065.rst
+++ b/Documentation/hwmon/max16065.rst
@@ -79,7 +79,7 @@ Usage Notes
 This driver does not probe for devices, since there is no register which
 can be safely used to identify the chip. You will have to instantiate
-the devices explicitly. Please see Documentation/i2c/instantiating-devices for
+the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 WARNING: Do not access chip registers using the i2cdump command, and do not use

--- a/Documentation/hwmon/max20751.rst
+++ b/Documentation/hwmon/max20751.rst
@@ -30,7 +30,7 @@ Usage Notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.

--- a/Documentation/hwmon/max34440.rst
+++ b/Documentation/hwmon/max34440.rst
@@ -83,7 +83,7 @@ Usage Notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 For MAX34446, the value of the currX_crit attribute determines if current or

--- a/Documentation/hwmon/max6650.rst
+++ b/Documentation/hwmon/max6650.rst
@@ -55,7 +55,7 @@ Usage notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 Module parameters

--- a/Documentation/hwmon/max8688.rst
+++ b/Documentation/hwmon/max8688.rst
@@ -28,7 +28,7 @@ Usage Notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.

--- a/Documentation/hwmon/menf21bmc.rst
+++ b/Documentation/hwmon/menf21bmc.rst
@@ -28,7 +28,7 @@ Usage Notes
 This driver is part of the MFD driver named "menf21bmc" and does
 not auto-detect devices.
 You will have to instantiate the MFD driver explicitly.
-Please see Documentation/i2c/instantiating-devices for
+Please see Documentation/i2c/instantiating-devices.rst for
 details.
 Sysfs entries

--- a/Documentation/hwmon/pcf8591.rst
+++ b/Documentation/hwmon/pcf8591.rst
@@ -68,7 +68,7 @@ Accessing PCF8591 via /sys interface
 The PCF8591 is plainly impossible to detect! Thus the driver won't even
 try. You have to explicitly instantiate the device at the relevant
 address (in the interval [0x48..0x4f]) either through platform data, or
-using the sysfs interface. See Documentation/i2c/instantiating-devices
+using the sysfs interface. See Documentation/i2c/instantiating-devices.rst
 for details.
 Directories are being created for each instantiated PCF8591:

--- a/Documentation/hwmon/sht3x.rst
+++ b/Documentation/hwmon/sht3x.rst
@@ -26,7 +26,7 @@ scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500.
 The device communicates with the I2C protocol. Sensors can have the I2C
 addresses 0x44 or 0x45, depending on the wiring. See
-Documentation/i2c/instantiating-devices for methods to instantiate the device.
+Documentation/i2c/instantiating-devices.rst for methods to instantiate the device.
 There are two options configurable by means of sht3x_platform_data:

--- a/Documentation/hwmon/shtc1.rst
+++ b/Documentation/hwmon/shtc1.rst
@@ -36,7 +36,7 @@ humidity is expressed as a percentage. Driver can be used as well for SHTW1
 chip, which has the same electrical interface.
 The device communicates with the I2C protocol. All sensors are set to I2C
-address 0x70. See Documentation/i2c/instantiating-devices for methods to
+address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to
 instantiate the device.
 There are two options configurable by means of shtc1_platform_data:

--- a/Documentation/hwmon/tmp103.rst
+++ b/Documentation/hwmon/tmp103.rst
@@ -30,4 +30,4 @@ The driver provides the common sysfs-interface for temperatures (see
 Documentation/hwmon/sysfs-interface.rst under Temperatures).
 Please refer how to instantiate this driver:
-Documentation/i2c/instantiating-devices
+Documentation/i2c/instantiating-devices.rst
--- a/Documentation/hwmon/tps40422.rst
+++ b/Documentation/hwmon/tps40422.rst
@@ -28,7 +28,7 @@ Usage Notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.

--- a/Documentation/hwmon/ucd9000.rst
+++ b/Documentation/hwmon/ucd9000.rst
@@ -64,7 +64,7 @@ Usage Notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.

--- a/Documentation/hwmon/ucd9200.rst
+++ b/Documentation/hwmon/ucd9200.rst
@@ -40,7 +40,7 @@ Usage Notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.

--- a/Documentation/hwmon/via686a.rst
+++ b/Documentation/hwmon/via686a.rst
@@ -40,7 +40,7 @@ all as a 686A.
 The Via 686a southbridge has integrated hardware monitor functionality.
 It also has an I2C bus, but this driver only supports the hardware monitor.
-For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro>
+For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro.rst>
 The Via 686a implements three temperature sensors, two fan rotation speed
 sensors, five voltage sensors and alarms.

--- a/Documentation/hwmon/zl6100.rst
+++ b/Documentation/hwmon/zl6100.rst
@@ -121,7 +121,7 @@ Usage Notes
 -----------
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 .. warning::

--- a/Documentation/i2c/busses/i2c-ali1535
+++ b/Documentation/i2c/busses/i2c-ali1535
+=========================
 Kernel driver i2c-ali1535
+=========================
 Supported adapters:
  * Acer Labs, Inc. ALI 1535 (south bridge)
    Datasheet: Now under NDA
 	http://www.ali.com.tw/
 Authors:
-	Frodo Looijaard <frodol@dds.nl>,
+	- Frodo Looijaard <frodol@dds.nl>,
-	Philip Edelbrock <phil@netroedge.com>,
+	- Philip Edelbrock <phil@netroedge.com>,
-	Mark D. Studebaker <mdsxyz123@yahoo.com>,
+	- Mark D. Studebaker <mdsxyz123@yahoo.com>,
-	Dan Eaton <dan.eaton@rocketlogix.com>,
+	- Dan Eaton <dan.eaton@rocketlogix.com>,
-	Stephen Rousset<stephen.rousset@rocketlogix.com>
+	- Stephen Rousset<stephen.rousset@rocketlogix.com>
 Description
 -----------

--- a/Documentation/i2c/busses/i2c-ali1563
+++ b/Documentation/i2c/busses/i2c-ali1563
+=========================
 Kernel driver i2c-ali1563
+=========================
 Supported adapters:
  * Acer Labs, Inc. ALI 1563 (south bridge)
    Datasheet: Now under NDA
 	http://www.ali.com.tw/

--- a/Documentation/i2c/busses/i2c-ali15x3
+++ b/Documentation/i2c/busses/i2c-ali15x3
+=========================
 Kernel driver i2c-ali15x3
+=========================
 Supported adapters:
  * Acer Labs, Inc. ALI 1533 and 1543C (south bridge)
    Datasheet: Now under NDA
 	http://www.ali.com.tw/
 Authors:
-	Frodo Looijaard <frodol@dds.nl>,
+	- Frodo Looijaard <frodol@dds.nl>,
-	Philip Edelbrock <phil@netroedge.com>,
+	- Philip Edelbrock <phil@netroedge.com>,
-	Mark D. Studebaker <mdsxyz123@yahoo.com>
+	- Mark D. Studebaker <mdsxyz123@yahoo.com>
 Module Parameters
 -----------------
@@ -25,7 +28,9 @@ the BIOS. Does not do a PCI force; the device must still be present in
 lspci. Don't use this unless the driver complains that the base address is
 not set.
-Example: 'modprobe i2c-ali15x3 force_addr=0xe800'
+Example::
+    modprobe i2c-ali15x3 force_addr=0xe800
 SMBus periodically hangs on ASUS P5A motherboards and can only be cleared
 by a power cycle. Cause unknown (see Issues below).
@@ -38,23 +43,26 @@ This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
 M1541 and M1543C South Bridges.
 The M1543C is a South bridge for desktop systems.
 The M1541 is a South bridge for portable systems.
 They are part of the following ALI chipsets:
 * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and
   100MHz CPU Front Side bus
 * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz
   CPU Front Side bus
   Some Aladdin V motherboards:
-	Asus P5A
+	- Asus P5A
-	Atrend ATC-5220
+	- Atrend ATC-5220
-	BCM/GVC VP1541
+	- BCM/GVC VP1541
-	Biostar M5ALA
+	- Biostar M5ALA
-	Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't
+	- Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't
-                            enable the 7101 device! **)
+	  enable the 7101 device!)
-	Iwill XA100 Plus
+	- Iwill XA100 Plus
-	Micronics C200
+	- Micronics C200
-	Microstar (MSI) MS-5169
+	- Microstar (MSI) MS-5169
  * "Aladdin IV" includes the M1541 Socket 7 North bridge
    with host bus up to 83.3 MHz.
@@ -64,21 +72,24 @@ full data sheets on the web site are password protected, however if you
 contact the ALI office in San Jose they may give you the password.
 The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An
-output of lspci will show something similar to the following:
+output of lspci will show something similar to the following::
  00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03)
  00:03.0 Bridge: Acer Laboratories Inc. M7101      <= THIS IS THE ONE WE NEED
  00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3)
  00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1)
-** IMPORTANT **
+.. important::
-** If you have a M1533 or M1543C on the board and you get
-** "ali15x3: Error: Can't detect ali15x3!"
+   If you have a M1533 or M1543C on the board and you get
-** then run lspci.
+   "ali15x3: Error: Can't detect ali15x3!"
-** If you see the 1533 and 5229 devices but NOT the 7101 device,
+   then run lspci.
-** then you must enable ACPI, the PMU, SMB, or something similar
-** in the BIOS.
+   If you see the 1533 and 5229 devices but NOT the 7101 device,
-** The driver won't work if it can't find the M7101 device.
+   then you must enable ACPI, the PMU, SMB, or something similar
+   in the BIOS.
+   The driver won't work if it can't find the M7101 device.
 The SMB controller is part of the M7101 device, which is an ACPI-compliant
 Power Management Unit (PMU).
@@ -109,4 +120,3 @@ There may be electrical problems on this board.
 On the P5A, the W83781D sensor chip is on both the ISA and
 SMBus. Therefore the SMBus hangs can generally be avoided
 by accessing the W83781D on the ISA bus only.
--- a/Documentation/i2c/busses/i2c-amd-mp2
+++ b/Documentation/i2c/busses/i2c-amd-mp2
+=========================
 Kernel driver i2c-amd-mp2
+=========================
 Supported adapters:
  * AMD MP2 PCIe interface
@@ -6,9 +8,9 @@ Supported adapters:
 Datasheet: not publicly available.
 Authors:
-	Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
+	- Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
-	Nehal Shah <nehal-bakulchandra.shah@amd.com>
+	- Nehal Shah <nehal-bakulchandra.shah@amd.com>
-	Elie Morisse <syniurge@gmail.com>
+	- Elie Morisse <syniurge@gmail.com>
 Description
 -----------
@@ -16,8 +18,8 @@ Description
 The MP2 is an ARM processor programmed as an I2C controller and communicating
 with the x86 host through PCI.
-If you see something like this:
+If you see something like this::
-03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
+  03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
-in your 'lspci -v', then this driver is for your device.
+in your ``lspci -v``, then this driver is for your device.
--- a/Documentation/i2c/busses/i2c-amd756
+++ b/Documentation/i2c/busses/i2c-amd756
+========================
 Kernel driver i2c-amd756
+========================
 Supported adapters:
  * AMD 756
  * AMD 766
  * AMD 768
  * AMD 8111
    Datasheets: Publicly available on AMD website
  * nVidia nForce
    Datasheet: Unavailable
 Authors:
-	Frodo Looijaard <frodol@dds.nl>,
+	- Frodo Looijaard <frodol@dds.nl>,
-	Philip Edelbrock <phil@netroedge.com> 
+	- Philip Edelbrock <phil@netroedge.com>
 Description
 -----------

--- a/Documentation/i2c/busses/i2c-amd8111
+++ b/Documentation/i2c/busses/i2c-amd8111
+=========================
 Kernel driver i2c-adm8111
+=========================
 Supported adapters:
    * AMD-8111 SMBus 2.0 PCI interface
@@ -13,14 +15,14 @@ Author: Vojtech Pavlik <vojtech@suse.cz>
 Description
 -----------
-If you see something like this:
+If you see something like this::
-00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
+  00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
          Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
          Flags: medium devsel, IRQ 19
          I/O ports at d400 [size=32]
-in your 'lspci -v', then this driver is for your chipset.
+in your ``lspci -v``, then this driver is for your chipset.
 Process Call Support
 --------------------

--- a/Documentation/i2c/busses/i2c-diolan-u2c
+++ b/Documentation/i2c/busses/i2c-diolan-u2c
+============================
 Kernel driver i2c-diolan-u2c
+============================
 Supported adapters:
  * Diolan U2C-12 I2C-USB adapter
    Documentation:
 	http://www.diolan.com/i2c/u2c12.html

--- a/Documentation/i2c/busses/i2c-i801
+++ b/Documentation/i2c/busses/i2c-i801
+======================
 Kernel driver i2c-i801
+======================
 Supported adapters:
  * Intel 82801AA and 82801AB (ICH and ICH0 - part of the
@@ -39,28 +42,33 @@ Supported adapters:
  * Intel Comet Lake (PCH)
  * Intel Elkhart Lake (PCH)
  * Intel Tiger Lake (PCH)
   Datasheets: Publicly available at the Intel website
 On Intel Patsburg and later chipsets, both the normal host SMBus controller
 and the additional 'Integrated Device Function' controllers are supported.
 Authors:
-	Mark Studebaker <mdsxyz123@yahoo.com>
+	- Mark Studebaker <mdsxyz123@yahoo.com>
-	Jean Delvare <jdelvare@suse.de>
+	- Jean Delvare <jdelvare@suse.de>
 Module Parameters
 -----------------
 * disable_features (bit vector)
 Disable selected features normally supported by the device. This makes it
 possible to work around possible driver or hardware bugs if the feature in
 question doesn't work as intended for whatever reason. Bit values:
+ ====  =========================================
 0x01  disable SMBus PEC
 0x02  disable the block buffer
 0x08  disable the I2C block read functionality
 0x10  don't use interrupts
 0x20  disable SMBus Host Notify
+ ====  =========================================
 Description
@@ -73,7 +81,7 @@ Pentium-based PCs, '815E' chipset, and others.
 The ICH chips contain at least SEVEN separate PCI functions in TWO logical
 PCI devices. An output of lspci will show something similar to the
-following:
+following::
  00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01)
  00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01)
@@ -139,9 +147,9 @@ and you think there's something interesting on the SMBus (e.g. a
 hardware monitoring chip), you need to add your board to the list.
 The motherboard is identified using the subvendor and subdevice IDs of the
-host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0":
+host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``::
-00:00.0 Class 0600: 8086:2570 (rev 02)
+  00:00.0 Class 0600: 8086:2570 (rev 02)
          Subsystem: 1043:80f2
          Flags: bus master, fast devsel, latency 0
          Memory at fc000000 (32-bit, prefetchable) [size=32M]
@@ -165,7 +173,8 @@ kernel. It's very convenient if you just want to check if there's
 anything interesting on your hidden ICH SMBus.
-**********************
+----------------------------------------------------------------------------
 The lm_sensors project gratefully acknowledges the support of Texas
 Instruments in the initial development of this driver.

--- a/Documentation/i2c/busses/i2c-ismt
+++ b/Documentation/i2c/busses/i2c-ismt
+======================
 Kernel driver i2c-ismt
+======================
 Supported adapters:
  * Intel S12xx series SOCs
@@ -11,16 +14,21 @@ Module Parameters
 -----------------
 * bus_speed (unsigned int)
 Allows changing of the bus speed.  Normally, the bus speed is set by the BIOS
 and never needs to be changed.  However, some SMBus analyzers are too slow for
 monitoring the bus during debug, thus the need for this module parameter.
 Specify the bus speed in kHz.
 Available bus frequency settings:
+  ====   =========
  0      no change
  80     kHz
  100    kHz
  400    kHz
  1000   kHz
+  ====   =========
 Description
@@ -30,7 +38,7 @@ The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers
 targeted primarily at the microserver and storage markets.
 The S12xx series contain a pair of PCI functions.  An output of lspci will show
-something similar to the following:
+something similar to the following::
  00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0
  00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1
--- a/Documentation/i2c/busses/i2c-mlxcpld
+++ b/Documentation/i2c/busses/i2c-mlxcpld
+==================
 Driver i2c-mlxcpld
+==================
 Author: Michael Shych <michaelsh@mellanox.com>
 This is the Mellanox I2C controller logic, implemented in Lattice CPLD
 device.
 Device supports:
 - Master mode.
 - One physical bus.
@@ -20,6 +23,8 @@ The next transaction types are supported:
 - Write Byte/Block.
 Registers:
+=============== === =======================================================================
 CPBLTY		0x0 - capability reg.
 			Bits [6:5] - transaction length. b01 - 72B is supported,
 			36B in other case.
@@ -49,3 +54,4 @@ DATAx		0xa - 0x54  - 68 bytes data buffer regs.
 			For read transactions address is sent in a separate transaction and
 			specified in the four first bytes (DATA0 - DATA3). Data is read
 			starting from DATA0.
+=============== === =======================================================================
--- a/Documentation/i2c/busses/i2c-nforce2
+++ b/Documentation/i2c/busses/i2c-nforce2
+=========================
 Kernel driver i2c-nforce2
+=========================
 Supported adapters:
  * nForce2 MCP                10de:0064
@@ -16,22 +18,23 @@ Supported adapters:
  * nForce MCP78S              10de:0752
  * nForce MCP79               10de:0AA2
-Datasheet: not publicly available, but seems to be similar to the
+Datasheet:
+           not publicly available, but seems to be similar to the
           AMD-8111 SMBus 2.0 adapter.
 Authors:
-	Hans-Frieder Vogt <hfvogt@gmx.net>,
+	- Hans-Frieder Vogt <hfvogt@gmx.net>,
-	Thomas Leibold <thomas@plx.com>, 
+	- Thomas Leibold <thomas@plx.com>,
-        Patrick Dreker <patrick@dreker.de>
+        - Patrick Dreker <patrick@dreker.de>
 Description
 -----------
 i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP.
-If your 'lspci -v' listing shows something like the following,
+If your ``lspci -v`` listing shows something like the following::
-00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
+  00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
          Subsystem: Asustek Computer, Inc.: Unknown device 0c11
          Flags: 66Mhz, fast devsel, IRQ 5
          I/O ports at c000 [size=32]

--- a/Documentation/i2c/busses/i2c-nvidia-gpu
+++ b/Documentation/i2c/busses/i2c-nvidia-gpu
+============================
 Kernel driver i2c-nvidia-gpu
+============================
 Datasheet: not publicly available.
@@ -11,8 +13,8 @@ Description
 i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing
 and later GPUs and it is used to communicate with Type-C controller on GPUs.
-If your 'lspci -v' listing shows something like the following,
+If your ``lspci -v`` listing shows something like the following::
-01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
+  01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
 then this driver should support the I2C controller of your GPU.
--- a/Documentation/i2c/busses/i2c-ocores
+++ b/Documentation/i2c/busses/i2c-ocores
+========================
 Kernel driver i2c-ocores
+========================
 Supported adapters:
  * OpenCores.org I2C controller by Richard Herveille (see datasheet link)
@@ -23,9 +25,9 @@ distance between registers and the input clock speed.
 There is also a possibility to attach a list of i2c_board_info which
 the i2c-ocores driver will add to the bus upon creation.
-E.G. something like:
+E.G. something like::
-static struct resource ocores_resources[] = {
+  static struct resource ocores_resources[] = {
 	[0] = {
 		.start	= MYI2C_BASEADDR,
 		.end	= MYI2C_BASEADDR + 8,
@@ -36,10 +38,10 @@ static struct resource ocores_resources[] = {
 		.end	= MYI2C_IRQ,
 		.flags	= IORESOURCE_IRQ,
 	},
-};
+  };
-/* optional board info */
+  /* optional board info */
-struct i2c_board_info ocores_i2c_board_info[] = {
+  struct i2c_board_info ocores_i2c_board_info[] = {
 	{
 		I2C_BOARD_INFO("tsc2003", 0x48),
 		.platform_data = &tsc2003_platform_data,
@@ -49,20 +51,20 @@ struct i2c_board_info ocores_i2c_board_info[] = {
 		I2C_BOARD_INFO("adv7180", 0x42 >> 1),
 		.irq = ADV_IRQ
 	}
-};
+  };
-static struct ocores_i2c_platform_data myi2c_data = {
+  static struct ocores_i2c_platform_data myi2c_data = {
 	.regstep	= 2,		/* two bytes between registers */
 	.clock_khz	= 50000,	/* input clock of 50MHz */
 	.devices	= ocores_i2c_board_info, /* optional table of devices */
 	.num_devices	= ARRAY_SIZE(ocores_i2c_board_info), /* table size */
-};
+  };
-static struct platform_device myi2c = {
+  static struct platform_device myi2c = {
 	.name			= "ocores-i2c",
 	.dev = {
 		.platform_data	= &myi2c_data,
 	},
 	.num_resources		= ARRAY_SIZE(ocores_resources),
 	.resource		= ocores_resources,
-};
+  };
--- a/Documentation/i2c/busses/i2c-parport-light
+++ b/Documentation/i2c/busses/i2c-parport-light
+===============================
 Kernel driver i2c-parport-light
+===============================
 Author: Jean Delvare <jdelvare@suse.de>

--- a/Documentation/i2c/busses/i2c-parport
+++ b/Documentation/i2c/busses/i2c-parport
+=========================
 Kernel driver i2c-parport
+=========================
 Author: Jean Delvare <jdelvare@suse.de>
 This is a unified driver for several i2c-over-parallel-port adapters,
 such as the ones made by Philips, Velleman or ELV. This driver is
 meant as a replacement for the older, individual drivers:
 * i2c-philips-par
 * i2c-elv
 * i2c-velleman
- * video/i2c-parport (NOT the same as this one, dedicated to home brew
+ * video/i2c-parport
-                      teletext adapters)
+   (NOT the same as this one, dedicated to home brew teletext adapters)
 It currently supports the following devices:
 * (type=0) Philips adapter
 * (type=1) home brew teletext adapter
 * (type=2) Velleman K8000 adapter
@@ -38,10 +42,10 @@ Building your own adapter
 -------------------------
 If you want to build you own i2c-over-parallel-port adapter, here is
-a sample electronics schema (credits go to Sylvain Munaut):
+a sample electronics schema (credits go to Sylvain Munaut)::
-Device                                                      PC
+  Device                                                      PC
-Side          ___________________Vdd (+)                    Side
+  Side          ___________________Vdd (+)                    Side
                 |    |         |
                ---  ---       ---
                | |  | |       | |
@@ -50,11 +54,11 @@ Side          ___________________Vdd (+)                    Side
                ---  ---       ---
                 |    |         |
                 |    |    /|   |
-SCL  ----------x--------o |-----------x-------------------  pin 2
+  SCL  ----------x--------o |-----------x-------------------  pin 2
                      |    \|   |       |
                      |         |       |
                      |   |\    |       |
-SDA  ----------x----x---| o---x---------------------------  pin 13
+  SDA  ----------x----x---| o---x---------------------------  pin 13
                 |        |/            |
                 |                      |
                 |         /|           |
@@ -73,9 +77,13 @@ SDA  ----------x----x---| o---x---------------------------  pin 13
 Remarks:
 - This is the exact pinout and electronics used on the Analog Devices
   evaluation boards.
+ - All inverters::
                   /|
- - All inverters -o |- must be 74HC05, they must be open collector output.
+                 -o |-
                   \|
+   must be 74HC05, they must be open collector output.
 - All resitors are 10k.
 - Pins 18-25 of the parallel port connected to GND.
 - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
@@ -88,11 +96,11 @@ Remarks:
 - This is 5V!
 - Obviously you cannot read SCL (so it's not really standard-compliant).
   Pretty easy to add, just copy the SDA part and use another input pin.
-   That would give (ELV compatible pinout):
+   That would give (ELV compatible pinout)::
-Device                                                      PC
+      Device                                                      PC
-Side          ______________________________Vdd (+)         Side
+      Side          ______________________________Vdd (+)         Side
                     |    |            |    |
                    ---  ---          ---  ---
                    | |  | |          | |  | |
@@ -101,7 +109,7 @@ Side          ______________________________Vdd (+)         Side
                    ---  ---          ---  ---
                     |    |            |    |
                     |    |      |\    |    |
-SCL  ----------x--------x--| o---x------------------------  pin 15
+      SCL  ----------x--------x--| o---x------------------------  pin 15
                          |   |  |/         |
                          |   |             |
                          |   |   /|        |
@@ -110,7 +118,7 @@ SCL  ----------x--------x--| o---x------------------------  pin 15
                          |                 |    |
                          |                 |    |
                          |      |\         |    |
-SDA  ---------------x---x--| o--------x-------------------  pin 10
+      SDA  ---------------x---x--| o--------x-------------------  pin 10
                              |  |/              |
                              |                  |
                              |   /|             |
@@ -149,19 +157,23 @@ Legacy documentation for Velleman adapter
 -----------------------------------------
 Useful links:
-Velleman                http://www.velleman.be/
-Velleman K8000 Howto    http://howto.htlw16.ac.at/k8000-howto.html
+- Velleman                http://www.velleman.be/
+- Velleman K8000 Howto    http://howto.htlw16.ac.at/k8000-howto.html
 The project has lead to new libs for the Velleman K8000 and K8005:
  LIBK8000 v1.99.1 and LIBK8005 v0.21
 With these libs, you can control the K8000 interface card and the K8005
 stepper motor card with the simple commands which are in the original
 Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
 many more, using /dev/velleman.
-  http://home.wanadoo.nl/hihihi/libk8000.htm
-  http://home.wanadoo.nl/hihihi/libk8005.htm
+  - http://home.wanadoo.nl/hihihi/libk8000.htm
-  http://struyve.mine.nu:8080/index.php?block=k8000
+  - http://home.wanadoo.nl/hihihi/libk8005.htm
-  http://sourceforge.net/projects/libk8005/
+  - http://struyve.mine.nu:8080/index.php?block=k8000
+  - http://sourceforge.net/projects/libk8005/
 One For All JP1 parallel port adapter

--- a/Documentation/i2c/busses/i2c-pca-isa
+++ b/Documentation/i2c/busses/i2c-pca-isa
+=========================
 Kernel driver i2c-pca-isa
+=========================
 Supported adapters:
 This driver supports ISA boards using the Philips PCA 9564
 Parallel bus to I2C bus controller

--- a/Documentation/i2c/busses/i2c-piix4
+++ b/Documentation/i2c/busses/i2c-piix4
+=======================
 Kernel driver i2c-piix4
+=======================
 Supported adapters:
  * Intel 82371AB PIIX4 and PIIX4E
@@ -21,8 +23,8 @@ Supported adapters:
    Datasheet: Publicly available at the SMSC website http://www.smsc.com
 Authors:
-	Frodo Looijaard <frodol@dds.nl>
+	- Frodo Looijaard <frodol@dds.nl>
-	Philip Edelbrock <phil@netroedge.com>
+	- Philip Edelbrock <phil@netroedge.com>
 Module Parameters
@@ -45,9 +47,9 @@ natively understands SMBus commands and you do not have to worry about
 timing problems. The bad news is that non-SMBus devices connected to it can
 confuse it mightily. Yes, this is known to happen...
-Do 'lspci -v' and see whether it contains an entry like this:
+Do ``lspci -v`` and see whether it contains an entry like this::
-0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
+  0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
 	       Flags: medium devsel, IRQ 9
 Bus and device numbers may differ, but the function number must be
@@ -91,7 +93,7 @@ the SMI mode.
   device is located at 00:0f.0.
 2) Now you just need to change the value in 0xD2 register. Get it first with
   command: lspci -xxx -s 00:0f.0
-   If the value is 0x3 then you need to change it to 0x1
+   If the value is 0x3 then you need to change it to 0x1:
   setpci  -s 00:0f.0 d2.b=1
 Please note that you don't need to do that in all cases, just when the SMBus is

--- a/Documentation/i2c/busses/i2c-sis5595
+++ b/Documentation/i2c/busses/i2c-sis5595
+=========================
 Kernel driver i2c-sis5595
+=========================
 Authors:
-	Frodo Looijaard <frodol@dds.nl>,
+	- Frodo Looijaard <frodol@dds.nl>,
-        Mark D. Studebaker <mdsxyz123@yahoo.com>,
+        - Mark D. Studebaker <mdsxyz123@yahoo.com>,
-	Philip Edelbrock <phil@netroedge.com>
+	- Philip Edelbrock <phil@netroedge.com>
 Supported adapters:
  * Silicon Integrated Systems Corp. SiS5595 Southbridge
@@ -11,14 +13,19 @@ Supported adapters:
 Note: all have mfr. ID 0x1039.
+   =========            ======
   SUPPORTED            PCI ID
+   =========            ======
        5595            0008
+   =========            ======
   Note: these chips contain a 0008 device which is incompatible with the
         5595. We recognize these by the presence of the listed
         "blacklist" PCI ID and refuse to load.
+   =============        ======          ================
   NOT SUPPORTED        PCI ID          BLACKLIST PCI ID
+   =============        ======          ================
         540            0008            0540
         550            0008            0550
        5513            0008            5511
@@ -36,15 +43,18 @@ Note: all have mfr. ID 0x1039.
         735            0008            0735
         745            0008            0745
         746            0008            0746
+   =============        ======          ================
 Module Parameters
 -----------------
-* force_addr=0xaddr	Set the I/O base address. Useful for boards
+==================	=====================================================
+force_addr=0xaddr	Set the I/O base address. Useful for boards
 			that don't set the address in the BIOS. Does not do a
 			PCI force; the device must still be present in lspci.
 			Don't use this unless the driver complains that the
 			base address is not set.
+==================	=====================================================
 Description
 -----------
@@ -56,4 +66,3 @@ WARNING: If you are trying to access the integrated sensors on the SiS5595
 chip, you want the sis5595 driver for those, not this driver. This driver
 is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP
 drivers to access chips on the bus.
--- a/Documentation/i2c/busses/i2c-sis630
+++ b/Documentation/i2c/busses/i2c-sis630
+========================
 Kernel driver i2c-sis630
+========================
 Supported adapters:
  * Silicon Integrated Systems Corp (SiS)
@@ -7,20 +9,24 @@ Supported adapters:
 	964 chipset
  * Possible other SiS chipsets ?
-Author: Alexander Malysh <amalysh@web.de>
+Author:
-	Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
+        - Alexander Malysh <amalysh@web.de>
+	- Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
 Module Parameters
 -----------------
-* force = [1|0] Forcibly enable the SIS630. DANGEROUS!
+==================      =====================================================
+force = [1|0]           Forcibly enable the SIS630. DANGEROUS!
                        This can be interesting for chipsets not named
-		above to check if it works for you chipset, but DANGEROUS!
+                        above to check if it works for you chipset,
+                        but DANGEROUS!
-* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
+high_clock = [1|0]      Forcibly set Host Master Clock to 56KHz (default,
 			what your BIOS use). DANGEROUS! This should be a bit
 			faster, but freeze some systems (i.e. my Laptop).
 			SIS630/730 chip only.
+==================      =====================================================
 Description
@@ -29,23 +35,23 @@ Description
 This SMBus only driver is known to work on motherboards with the above
 named chipsets.
-If you see something like this:
+If you see something like this::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+  00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-or like this:
+or like this::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+  00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-or like this:
+or like this::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
+  00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
 							LPC Controller (rev 36)
-in your 'lspci' output , then this driver is for your chipset.
+in your ``lspci`` output , then this driver is for your chipset.
 Thank You
 ---------
@@ -55,4 +61,3 @@ Mark M. Hoffman <mhoffman@lightlink.com>
 - bug fixes
 To anyone else which I forgot here ;), thanks!
--- a/Documentation/i2c/busses/i2c-sis96x
+++ b/Documentation/i2c/busses/i2c-sis96x
+========================
 Kernel driver i2c-sis96x
+========================
 Replaces 2.4.x i2c-sis645
 Supported adapters:
  * Silicon Integrated Systems Corp (SiS)
    Any combination of these host bridges:
 	645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746
    and these south bridges:
 	961, 962, 963(L)
@@ -21,17 +26,17 @@ those of the SiS630, although they are located in a completely different
 place. Thanks to Alexander Malysh <amalysh@web.de> for providing the
 SiS630 datasheet (and  driver).
-The command "lspci" as root should produce something like these lines:
+The command ``lspci`` as root should produce something like these lines::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+  00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+  00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
-or perhaps this...
+or perhaps this::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
+  00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+  00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
 (kernel versions later than 2.4.18 may fill in the "Unknown"s)
@@ -50,7 +55,7 @@ TO DOs
 ------
 * The driver does not support SMBus block reads/writes; I may add them if a
-scenario is found where they're needed.
+  scenario is found where they're needed.
 Thank You
@@ -58,16 +63,20 @@ Thank You
 Mark D. Studebaker <mdsxyz123@yahoo.com>
 - design hints and bug fixes
 Alexander Maylsh <amalysh@web.de>
 - ditto, plus an important datasheet... almost the one I really wanted
 Hans-Günter Lütke Uphues <hg_lu@t-online.de>
 - patch for SiS735
 Robert Zwerus <arzie@dds.nl>
 - testing for SiS645DX
 Kianusch Sayah Karadji <kianusch@sk-tech.net>
 - patch for SiS645DX/962
 Ken Healy
 - patch for SiS655
 To anyone else who has written w/ feedback, thanks!
--- a/Documentation/i2c/busses/i2c-taos-evm
+++ b/Documentation/i2c/busses/i2c-taos-evm
+==========================
 Kernel driver i2c-taos-evm
+==========================
 Author: Jean Delvare <jdelvare@suse.de>
@@ -23,10 +25,10 @@ Using this driver
 In order to use this driver, you'll need the serport driver, and the
 inputattach tool, which is part of the input-utils package. The following
 commands will tell the kernel that you have a TAOS EVM on the first
-serial port:
+serial port::
-# modprobe serport
+  # modprobe serport
-# inputattach --taos-evm /dev/ttyS0
+  # inputattach --taos-evm /dev/ttyS0
 Technical details

--- a/Documentation/i2c/busses/i2c-via
+++ b/Documentation/i2c/busses/i2c-via
+=====================
 Kernel driver i2c-via
+=====================
 Supported adapters:
  * VIA Technologies, InC. VT82C586B
@@ -15,20 +17,24 @@ The following VIA pci chipsets are supported:
 - MVP3, VP3, VP2/97, VPX/97
 - others with South bridge VT82C586B
-Your lspci listing must show this :
+Your ``lspci`` listing must show this ::
 Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10)
-    Problems?
+Problems?
+---------
- Q: You have VT82C586B on the motherboard, but not in the listing. 
+ Q:
+    You have VT82C586B on the motherboard, but not in the listing.
- A: Go to your BIOS setup, section PCI devices or similar.
+ A:
+    Go to your BIOS setup, section PCI devices or similar.
    Turn USB support on, and try again.
- Q: No error messages, but still i2c doesn't seem to work.
+ Q:
+    No error messages, but still i2c doesn't seem to work.
- A: This can happen. This driver uses the pins VIA recommends in their
+ A:
+    This can happen. This driver uses the pins VIA recommends in their
    datasheets, but there are several ways the motherboard manufacturer
    can actually wire the lines.
--- a/Documentation/i2c/busses/i2c-viapro
+++ b/Documentation/i2c/busses/i2c-viapro
+========================
 Kernel driver i2c-viapro
+========================
 Supported adapters:
  * VIA Technologies, Inc. VT82C596A/B
@@ -26,9 +28,9 @@ Supported adapters:
    Datasheet: available on http://linux.via.com.tw
 Authors:
-	Kyösti Mälkki <kmalkki@cc.hut.fi>,
+	- Kyösti Mälkki <kmalkki@cc.hut.fi>,
-	Mark D. Studebaker <mdsxyz123@yahoo.com>,
+	- Mark D. Studebaker <mdsxyz123@yahoo.com>,
-	Jean Delvare <jdelvare@suse.de>
+	- Jean Delvare <jdelvare@suse.de>
 Module Parameters
 -----------------
@@ -44,8 +46,9 @@ Description
 i2c-viapro is a true SMBus host driver for motherboards with one of the
 supported VIA south bridges.
-Your lspci -n listing must show one of these :
+Your ``lspci -n`` listing must show one of these :
+ ================   ======================
 device 1106:3050   (VT82C596A function 3)
 device 1106:3051   (VT82C596B function 3)
 device 1106:3057   (VT82C686 function 4)
@@ -61,6 +64,7 @@ Your lspci -n listing must show one of these :
 device 1106:8353   (VX800/VX820)
 device 1106:8409   (VX855/VX875)
 device 1106:8410   (VX900)
+ ================   ======================
 If none of these show up, you should look in the BIOS for settings like
 enable ACPI / SMBus or even USB.

--- a/Documentation/i2c/busses/index.rst
+++ b/Documentation/i2c/busses/index.rst
+. SPDX-License-Identifier: GPL-2.0
+===============
+I2C Bus Drivers
+===============
+.. toctree::
+   :maxdepth: 1
+   i2c-ali1535
+   i2c-ali1563
+   i2c-ali15x3
+   i2c-amd756
+   i2c-amd8111
+   i2c-amd-mp2
+   i2c-diolan-u2c
+   i2c-i801
+   i2c-ismt
+   i2c-mlxcpld
+   i2c-nforce2
+   i2c-nvidia-gpu
+   i2c-ocores
+   i2c-parport-light
+   i2c-parport
+   i2c-pca-isa
+   i2c-piix4
+   i2c-sis5595
+   i2c-sis630
+   i2c-sis96x
+   i2c-taos-evm
+   i2c-viapro
+   i2c-via
+   scx200_acb
--- a/Documentation/i2c/busses/scx200_acb
+++ b/Documentation/i2c/busses/scx200_acb
+========================
 Kernel driver scx200_acb
+========================
 Author: Christer Weinigel <wingel@nano-system.com>
@@ -25,8 +27,11 @@ Device-specific notes
 The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820.
 If the scx200_acb driver is built into the kernel, add the following
-parameter to your boot command line:
+parameter to your boot command line::
  scx200_acb.base=0x810,0x820
 If the scx200_acb driver is built as a module, add the following line to
-a configuration file in /etc/modprobe.d/ instead:
+a configuration file in /etc/modprobe.d/ instead::
  options scx200_acb base=0x810,0x820
--- a/Documentation/i2c/dev-interface
+++ b/Documentation/i2c/dev-interface
+====================
+I2C Device Interface
+====================
 Usually, i2c devices are controlled by a kernel driver. But it is also
 possible to access all devices on an adapter from userspace, through
 the /dev interface. You need to load module i2c-dev for this.
@@ -18,7 +22,7 @@ C example
 =========
 So let's say you want to access an i2c adapter from a C program.
-First, you need to include these two headers:
+First, you need to include these two headers::
  #include <linux/i2c-dev.h>
  #include <i2c/smbus.h>
@@ -28,7 +32,7 @@ inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
 Adapter numbers are assigned somewhat dynamically, so you can not
 assume much about them. They can even change from one boot to the next.
-Next thing, open the device file, as follows:
+Next thing, open the device file, as follows::
  int file;
  int adapter_nr = 2; /* probably dynamically determined */
@@ -42,7 +46,7 @@ Next thing, open the device file, as follows:
  }
 When you have opened the device, you must specify with what device
-address you want to communicate:
+address you want to communicate::
  int addr = 0x40; /* The I2C address */
@@ -53,7 +57,7 @@ address you want to communicate:
 Well, you are all set up now. You can now use SMBus commands or plain
 I2C to communicate with your device. SMBus commands are preferred if
-the device supports them. Both are illustrated below.
+the device supports them. Both are illustrated below::
  __u8 reg = 0x10; /* Device register to access */
  __s32 res;
@@ -100,30 +104,30 @@ Full interface description
 The following IOCTLs are defined:
-ioctl(file, I2C_SLAVE, long addr)
+``ioctl(file, I2C_SLAVE, long addr)``
  Change slave address. The address is passed in the 7 lower bits of the
  argument (except for 10 bit addresses, passed in the 10 lower bits in this
  case).
-ioctl(file, I2C_TENBIT, long select)
+``ioctl(file, I2C_TENBIT, long select)``
  Selects ten bit addresses if select not equals 0, selects normal 7 bit
  addresses if select equals 0. Default 0.  This request is only valid
  if the adapter has I2C_FUNC_10BIT_ADDR.
-ioctl(file, I2C_PEC, long select)
+``ioctl(file, I2C_PEC, long select)``
  Selects SMBus PEC (packet error checking) generation and verification
  if select not equals 0, disables if select equals 0. Default 0.
  Used only for SMBus transactions.  This request only has an effect if the
  the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just
  doesn't have any effect.
-ioctl(file, I2C_FUNCS, unsigned long *funcs)
+``ioctl(file, I2C_FUNCS, unsigned long *funcs)``
-  Gets the adapter functionality and puts it in *funcs.
+  Gets the adapter functionality and puts it in ``*funcs``.
-ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
+``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)``
  Do combined read/write transaction without stop in between.
  Only valid if the adapter has I2C_FUNC_I2C.  The argument is
-  a pointer to a
+  a pointer to a::
    struct i2c_rdwr_ioctl_data {
      struct i2c_msg *msgs;  /* ptr to array of simple messages */
@@ -136,8 +140,8 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
  The slave address and whether to use ten bit address mode has to be
  set in each message, overriding the values set with the above ioctl's.
-ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)
+``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)``
-  If possible, use the provided i2c_smbus_* methods described below instead
+  If possible, use the provided ``i2c_smbus_*`` methods described below instead
  of issuing direct ioctls.
 You can do plain i2c transactions by using read(2) and write(2) calls.
@@ -145,7 +149,8 @@ You do not need to pass the address byte; instead, set it through
 ioctl I2C_SLAVE before you try to access the device.
 You can do SMBus level transactions (see documentation file smbus-protocol
-for details) through the following functions:
+for details) through the following functions::
  __s32 i2c_smbus_write_quick(int file, __u8 value);
  __s32 i2c_smbus_read_byte(int file);
  __s32 i2c_smbus_write_byte(int file, __u8 value);
@@ -157,6 +162,7 @@ for details) through the following functions:
  __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
  __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
                                   __u8 *values);
 All these transactions return -1 on failure; you can read errno to see
 what happened. The 'write' transactions return 0 on success; the
 'read' transactions return the read value, except for read_block, which
@@ -174,39 +180,39 @@ Implementation details
 For the interested, here's the code flow which happens inside the kernel
 when you use the /dev interface to I2C:
-1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in
+1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in
-section "C example" above.
+   section "C example" above.
-2* These open() and ioctl() calls are handled by the i2c-dev kernel
+2) These open() and ioctl() calls are handled by the i2c-dev kernel
-driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
+   driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
-respectively. You can think of i2c-dev as a generic I2C chip driver
+   respectively. You can think of i2c-dev as a generic I2C chip driver
-that can be programmed from user-space.
+   that can be programmed from user-space.
-3* Some ioctl() calls are for administrative tasks and are handled by
+3) Some ioctl() calls are for administrative tasks and are handled by
-i2c-dev directly. Examples include I2C_SLAVE (set the address of the
+   i2c-dev directly. Examples include I2C_SLAVE (set the address of the
-device you want to access) and I2C_PEC (enable or disable SMBus error
+   device you want to access) and I2C_PEC (enable or disable SMBus error
-checking on future transactions.)
+   checking on future transactions.)
-4* Other ioctl() calls are converted to in-kernel function calls by
+4) Other ioctl() calls are converted to in-kernel function calls by
-i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
+   i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
-functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
+   functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
-performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
+   performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
-The i2c-dev driver is responsible for checking all the parameters that
+   The i2c-dev driver is responsible for checking all the parameters that
-come from user-space for validity. After this point, there is no
+   come from user-space for validity. After this point, there is no
-difference between these calls that came from user-space through i2c-dev
+   difference between these calls that came from user-space through i2c-dev
-and calls that would have been performed by kernel I2C chip drivers
+   and calls that would have been performed by kernel I2C chip drivers
-directly. This means that I2C bus drivers don't need to implement
+   directly. This means that I2C bus drivers don't need to implement
-anything special to support access from user-space.
+   anything special to support access from user-space.
-5* These i2c.h functions are wrappers to the actual implementation of
+5) These i2c.h functions are wrappers to the actual implementation of
-your I2C bus driver. Each adapter must declare callback functions
+   your I2C bus driver. Each adapter must declare callback functions
-implementing these standard calls. i2c.h:i2c_get_functionality() calls
+   implementing these standard calls. i2c.h:i2c_get_functionality() calls
-i2c_adapter.algo->functionality(), while
+   i2c_adapter.algo->functionality(), while
-i2c-core-smbus.c:i2c_smbus_xfer() calls either
+   i2c-core-smbus.c:i2c_smbus_xfer() calls either
-adapter.algo->smbus_xfer() if it is implemented, or if not,
+   adapter.algo->smbus_xfer() if it is implemented, or if not,
-i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
+   i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
-i2c_adapter.algo->master_xfer().
+   i2c_adapter.algo->master_xfer().
 After your I2C bus driver has processed these requests, execution runs
 up the call chain, with almost no processing done, except by i2c-dev to

--- a/Documentation/i2c/DMA-considerations
+++ b/Documentation/i2c/DMA-considerations
--- a/Documentation/i2c/fault-codes
+++ b/Documentation/i2c/fault-codes
+=====================
+I2C/SMBUS Fault Codes
+=====================
 This is a summary of the most important conventions for use of fault
 codes in the I2C/SMBus stack.
@@ -125,4 +129,3 @@ ETIMEDOUT
 	when a slave stretches clocks too far.  I2C has no such
 	timeouts, but it's normal for I2C adapters to impose some
 	arbitrary limits (much longer than SMBus!) too.
--- a/Documentation/i2c/functionality
+++ b/Documentation/i2c/functionality
+=======================
+I2C/SMBus Functionality
+=======================
 INTRODUCTION
 ------------
@@ -14,6 +18,7 @@ FUNCTIONALITY CONSTANTS
 For the most up-to-date list of functionality constants, please check
 <uapi/linux/i2c.h>!
+  =============================== ==============================================
  I2C_FUNC_I2C                    Plain i2c-level commands (Pure SMBus
                                  adapters typically can not do these)
  I2C_FUNC_10BIT_ADDR             Handles the 10-bit address extensions
@@ -33,9 +38,11 @@ For the most up-to-date list of functionality constants, please check
  I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command
  I2C_FUNC_SMBUS_READ_I2C_BLOCK   Handles the SMBus read_i2c_block_data command
  I2C_FUNC_SMBUS_WRITE_I2C_BLOCK  Handles the SMBus write_i2c_block_data command
+  =============================== ==============================================
 A few combinations of the above flags are also defined for your convenience:
+  =========================       ======================================
  I2C_FUNC_SMBUS_BYTE             Handles the SMBus read_byte
                                  and write_byte commands
  I2C_FUNC_SMBUS_BYTE_DATA        Handles the SMBus read_byte_data
@@ -49,6 +56,7 @@ A few combinations of the above flags are also defined for your convenience:
  I2C_FUNC_SMBUS_EMUL             Handles all SMBus commands that can be
                                  emulated by a real I2C adapter (using
                                  the transparent emulation layer)
+  =========================       ======================================
 In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as
 part of I2C_FUNC_PROTOCOL_MANGLING.
@@ -58,11 +66,11 @@ ADAPTER IMPLEMENTATION
 ----------------------
 When you write a new adapter driver, you will have to implement a
-function callback `functionality'. Typical implementations are given
+function callback ``functionality``. Typical implementations are given
 below.
 A typical SMBus-only adapter would list all the SMBus transactions it
-supports. This example comes from the i2c-piix4 driver:
+supports. This example comes from the i2c-piix4 driver::
  static u32 piix4_func(struct i2c_adapter *adapter)
  {
@@ -72,7 +80,7 @@ supports. This example comes from the i2c-piix4 driver:
  }
 A typical full-I2C adapter would use the following (from the i2c-pxa
-driver):
+driver)::
  static u32 i2c_pxa_functionality(struct i2c_adapter *adap)
  {
@@ -94,7 +102,7 @@ CLIENT CHECKING
 Before a client tries to attach to an adapter, or even do tests to check
 whether one of the devices it supports is present on an adapter, it should
 check whether the needed functionality is present. The typical way to do
-this is (from the lm75 driver):
+this is (from the lm75 driver)::
  static int lm75_detect(...)
  {
@@ -129,7 +137,7 @@ If you try to access an adapter from a userspace program, you will have
 to use the /dev interface. You will still have to check whether the
 functionality you need is supported, of course. This is done using
 the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is
-below:
+below::
  int file;
  if (file = open("/dev/i2c-0", O_RDWR) < 0) {

--- a/Documentation/i2c/gpio-fault-injection
+++ b/Documentation/i2c/gpio-fault-injection
@@ -104,10 +104,10 @@ There doesn't need to be a device at this address because arbitration lost
 should be detected beforehand. Also note, that SCL going down is monitored
 using interrupts, so the interrupt latency might cause the first bits to be not
 corrupted. A good starting point for using this fault injector on an otherwise
-idle bus is:
+idle bus is::
-# echo 200 > lose_arbitration &
+  # echo 200 > lose_arbitration &
-# i2cget -y <bus_to_test> 0x3f
+  # i2cget -y <bus_to_test> 0x3f
 Panic during transfer
 =====================
@@ -127,10 +127,10 @@ The calling process will then sleep and wait for the next bus clock. The
 process is interruptible, though.
 Start of a transfer is detected by waiting for SCL going down by the master
-under test.  A good starting point for using this fault injector is:
+under test.  A good starting point for using this fault injector is::
-# echo 0 > inject_panic &
+  # echo 0 > inject_panic &
-# i2cget -y <bus_to_test> <some_address>
+  # i2cget -y <bus_to_test> <some_address>
 Note that there doesn't need to be a device listening to the address you are
 using. Results may vary depending on that, though.
--- a/Documentation/i2c/i2c-protocol
+++ b/Documentation/i2c/i2c-protocol
+============
+I2C Protocol
+============
 This document describes the i2c protocol. Or will, when it is finished :-)
 Key to symbols
 ==============
+=============== =============================================================
 S     (1 bit) : Start bit
 P     (1 bit) : Stop bit
 Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
@@ -15,33 +20,35 @@ Data  (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
                for 16 bit data.
 Count (8 bits): A data byte containing the length of a block operation.
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
+[..]:           Data sent by I2C device, as opposed to data sent by the
+                host adapter.
+=============== =============================================================
 Simple send transaction
-======================
+=======================
-This corresponds to i2c_master_send.
+This corresponds to i2c_master_send::
  S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
 Simple receive transaction
-===========================
+==========================
-This corresponds to i2c_master_recv
+This corresponds to i2c_master_recv::
  S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
 Combined transactions
-====================
+=====================
 This corresponds to i2c_transfer
 They are just like the above transactions, but instead of a stop bit P
 a start bit S is sent and the transaction continues. An example of
-a byte read, followed by a byte write:
+a byte read, followed by a byte write::
  S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
@@ -65,8 +72,10 @@ I2C_M_NO_RD_ACK:
 I2C_M_NOSTART:
    In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
    point. For example, setting I2C_M_NOSTART on the second partial message
-    generates something like:
+    generates something like::
      S Addr Rd [A] [Data] NA Data [A] P
    If you set the I2C_M_NOSTART variable for the first partial message,
    we do not generate Addr, but we do generate the startbit S. This will
    probably confuse all other clients on your bus, so don't try this.
@@ -79,7 +88,8 @@ I2C_M_NOSTART:
 I2C_M_REV_DIR_ADDR:
    This toggles the Rd/Wr flag. That is, if you want to do a write, but
    need to emit an Rd instead of a Wr, or vice versa, you set this
-    flag. For example:
+    flag. For example::
      S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
 I2C_M_STOP:

--- a/Documentation/i2c/i2c-stub
+++ b/Documentation/i2c/i2c-stub
-MODULE: i2c-stub
+========
+i2c-stub
+========
-DESCRIPTION:
+Description
+===========
 This module is a very simple fake I2C/SMBus driver.  It implements six
 types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w)
@@ -28,6 +31,7 @@ SMBus block operations. Writes can be partial. Block read commands always
 return the number of bytes selected with the largest write so far.
 The typical use-case is like this:
 	1. load this module
 	2. use i2cset (from the i2c-tools project) to pre-load some data
 	3. load the target chip driver module
@@ -36,7 +40,8 @@ The typical use-case is like this:
 There's a script named i2c-stub-from-dump in the i2c-tools package which
 can load register values automatically from a chip dump.
-PARAMETERS:
+Parameters
+==========
 int chip_addr[10]:
 	The SMBus addresses to emulate chips at.
@@ -47,18 +52,15 @@ unsigned long functionality:
 	value 0x1f0000 would only enable the quick, byte and byte data
 	commands.
-u8 bank_reg[10]
+u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]:
-u8 bank_mask[10]
-u8 bank_start[10]
-u8 bank_end[10]:
 	Optional bank settings. They tell which bits in which register
 	select the active bank, as well as the range of banked registers.
-CAVEATS:
+Caveats
+=======
 If your target driver polls some byte or word waiting for it to change, the
 stub could lock it up.  Use i2cset to unlock it.
 If you spam it hard enough, printk can be lossy.  This module really wants
 something like relayfs.
--- a/Documentation/i2c/i2c-topology
+++ b/Documentation/i2c/i2c-topology
+============
 I2C topology
 ============
@@ -14,6 +15,7 @@ than a straight-forward i2c bus with one adapter and one or more devices.
   that has to be operated before the device can be accessed.
 Etc
+===
 These constructs are represented as i2c adapter trees by Linux, where
 each adapter has a parent adapter (except the root adapter) and zero or
@@ -37,7 +39,9 @@ mux-locked or parent-locked muxes. As is evident from below, it can be
 useful to know if a mux is mux-locked or if it is parent-locked. The
 following list was correct at the time of writing:
-In drivers/i2c/muxes/
+In drivers/i2c/muxes/:
+======================    =============================================
 i2c-arb-gpio-challenge    Parent-locked
 i2c-mux-gpio              Normally parent-locked, mux-locked iff
                          all involved gpio pins are controlled by the
@@ -52,18 +56,25 @@ i2c-mux-pinctrl           Normally parent-locked, mux-locked iff
                          all involved pinctrl devices are controlled
                          by the same i2c root adapter that they mux.
 i2c-mux-reg               Parent-locked
+======================    =============================================
-In drivers/iio/
+In drivers/iio/:
+======================    =============================================
 gyro/mpu3050              Mux-locked
 imu/inv_mpu6050/          Mux-locked
+======================    =============================================
+In drivers/media/:
-In drivers/media/
+=======================   =============================================
 dvb-frontends/lgdt3306a   Mux-locked
 dvb-frontends/m88ds3103   Parent-locked
 dvb-frontends/rtl2830     Parent-locked
 dvb-frontends/rtl2832     Mux-locked
 dvb-frontends/si2168      Mux-locked
 usb/cx231xx/              Parent-locked
+=======================   =============================================
 Mux-locked muxes
@@ -78,6 +89,7 @@ full transaction, unrelated i2c transfers may interleave the different
 stages of the transaction. This has the benefit that the mux driver
 may be easier and cleaner to implement, but it has some caveats.
+==== =====================================================================
 ML1. If you build a topology with a mux-locked mux being the parent
     of a parent-locked mux, this might break the expectation from the
     parent-locked mux that the root adapter is locked during the
@@ -105,11 +117,15 @@ ML4. If any non-i2c operation in the mux driver changes the i2c mux state,
     Otherwise garbage may appear on the bus as seen from devices
     behind the mux, when an unrelated i2c transfer is in flight during
     the non-i2c mux-changing operation.
+==== =====================================================================
 Mux-locked Example
 ------------------
+::
                   .----------.     .--------.
    .--------.     |   mux-   |-----| dev D1 |
    |  root  |--+--|  locked  |     '--------'
@@ -148,6 +164,7 @@ adapter during the transaction are unlocked i2c transfers (using e.g.
 __i2c_transfer), or a deadlock will follow. There are a couple of
 caveats.
+==== ====================================================================
 PL1. If you build a topology with a parent-locked mux being the child
     of another mux, this might break a possible assumption from the
     child mux that the root adapter is unused between its select op
@@ -161,11 +178,14 @@ PL2. If select/deselect calls out to other subsystems such as gpio,
     caused by these subsystems are unlocked. This can be convoluted to
     accomplish, maybe even impossible if an acceptably clean solution
     is sought.
+==== ====================================================================
 Parent-locked Example
 ---------------------
+::
                   .----------.     .--------.
    .--------.     |  parent- |-----| dev D1 |
    |  root  |--+--|  locked  |     '--------'
@@ -190,7 +210,7 @@ When there is an access to D1, this happens:
 7.  M1 calls ->deselect, if it has one.
 8.  Same rules as in step 5, but for ->deselect.
 9.  M1 unlocks its parent adapter.
-10. M1 unlocks muxes on its parent.
+ 10. M1 unlocks muxes on its parent.
 This means that accesses to both D2 and D3 are locked out for the full
@@ -203,7 +223,7 @@ Complex Examples
 Parent-locked mux as parent of parent-locked mux
 ------------------------------------------------
-This is a useful topology, but it can be bad.
+This is a useful topology, but it can be bad::
                   .----------.     .----------.     .--------.
    .--------.     |  parent- |-----|  parent- |-----| dev D1 |
@@ -227,7 +247,7 @@ through and be seen by the M2 adapter, thus closing M2 prematurely.
 Mux-locked mux as parent of mux-locked mux
 ------------------------------------------
-This is a good topology.
+This is a good topology::
                   .----------.     .----------.     .--------.
    .--------.     |   mux-   |-----|   mux-   |-----| dev D1 |
@@ -248,7 +268,7 @@ are still possibly interleaved.
 Mux-locked mux as parent of parent-locked mux
 ---------------------------------------------
-This is probably a bad topology.
+This is probably a bad topology::
                   .----------.     .----------.     .--------.
    .--------.     |   mux-   |-----|  parent- |-----| dev D1 |
@@ -282,7 +302,7 @@ auto-closing, the topology is fine.
 Parent-locked mux as parent of mux-locked mux
 ---------------------------------------------
-This is a good topology.
+This is a good topology::
                   .----------.     .----------.     .--------.
    .--------.     |  parent- |-----|   mux-   |-----| dev D1 |
@@ -306,7 +326,7 @@ adapter is locked directly.
 Two mux-locked sibling muxes
 ----------------------------
-This is a good topology.
+This is a good topology::
                                    .--------.
                   .----------.  .--| dev D1 |
@@ -330,7 +350,7 @@ accesses to D5 may be interleaved at any time.
 Two parent-locked sibling muxes
 -------------------------------
-This is a good topology.
+This is a good topology::
                                    .--------.
                   .----------.  .--| dev D1 |
@@ -354,7 +374,7 @@ out.
 Mux-locked and parent-locked sibling muxes
 ------------------------------------------
-This is a good topology.
+This is a good topology::
                                    .--------.
                   .----------.  .--| dev D1 |

--- a/Documentation/i2c/index.rst
+++ b/Documentation/i2c/index.rst
+. SPDX-License-Identifier: GPL-2.0
+===================
+I2C/SMBus Subsystem
+===================
+.. toctree::
+   :maxdepth: 1
+   dev-interface
+   dma-considerations
+   fault-codes
+   functionality
+   gpio-fault-injection
+   i2c-protocol
+   i2c-stub
+   i2c-topology
+   instantiating-devices
+   old-module-parameters
+   slave-eeprom-backend
+   slave-interface
+   smbus-protocol
+   summary
+   ten-bit-addresses
+   upgrading-clients
+   writing-clients
+   muxes/i2c-mux-gpio
+   busses/index
+.. only::  subproject and html
+   Indices
+   =======
+   * :ref:`genindex`
--- a/Documentation/i2c/instantiating-devices
+++ b/Documentation/i2c/instantiating-devices
+==============================
 How to instantiate I2C devices
 ==============================
@@ -17,9 +18,9 @@ which is known in advance. It is thus possible to pre-declare the I2C
 devices which live on this bus. This is done with an array of struct
 i2c_board_info which is registered by calling i2c_register_board_info().
-Example (from omap2 h4):
+Example (from omap2 h4)::
-static struct i2c_board_info h4_i2c_board_info[] __initdata = {
+  static struct i2c_board_info h4_i2c_board_info[] __initdata = {
 	{
 		I2C_BOARD_INFO("isp1301_omap", 0x2d),
 		.irq		= OMAP_GPIO_IRQ(125),
@@ -32,15 +33,15 @@ static struct i2c_board_info h4_i2c_board_info[] __initdata = {
 		I2C_BOARD_INFO("24c01", 0x57),
 		.platform_data	= &m24c01,
 	},
-};
+  };
-static void __init omap_h4_init(void)
+  static void __init omap_h4_init(void)
-{
+  {
 	(...)
 	i2c_register_board_info(1, h4_i2c_board_info,
 			ARRAY_SIZE(h4_i2c_board_info));
 	(...)
-}
+  }
 The above code declares 3 devices on I2C bus 1, including their respective
 addresses and custom data needed by their drivers. When the I2C bus in
@@ -57,7 +58,7 @@ Method 1b: Declare the I2C devices via devicetree
 This method has the same implications as method 1a. The declaration of I2C
 devices is here done via devicetree as subnodes of the master controller.
-Example:
+Example::
 	i2c1: i2c@400a0000 {
 		/* ... master properties skipped ... */
@@ -99,20 +100,20 @@ bus in advance, so the method 1 described above can't be used. Instead,
 you can instantiate your I2C devices explicitly. This is done by filling
 a struct i2c_board_info and calling i2c_new_device().
-Example (from the sfe4001 network driver):
+Example (from the sfe4001 network driver)::
-static struct i2c_board_info sfe4001_hwmon_info = {
+  static struct i2c_board_info sfe4001_hwmon_info = {
 	I2C_BOARD_INFO("max6647", 0x4e),
-};
+  };
-int sfe4001_init(struct efx_nic *efx)
+  int sfe4001_init(struct efx_nic *efx)
-{
+  {
 	(...)
 	efx->board_info.hwmon_client =
 		i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info);
 	(...)
-}
+  }
 The above code instantiates 1 I2C device on the I2C bus which is on the
 network adapter in question.
@@ -124,12 +125,12 @@ it may have different addresses from one board to the next (manufacturer
 changing its design without notice). In this case, you can call
 i2c_new_probed_device() instead of i2c_new_device().
-Example (from the nxp OHCI driver):
+Example (from the nxp OHCI driver)::
-static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
+  static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
-static int usb_hcd_nxp_probe(struct platform_device *pdev)
+  static int usb_hcd_nxp_probe(struct platform_device *pdev)
-{
+  {
 	(...)
 	struct i2c_adapter *i2c_adap;
 	struct i2c_board_info i2c_info;
@@ -142,7 +143,7 @@ static int usb_hcd_nxp_probe(struct platform_device *pdev)
 						   normal_i2c, NULL);
 	i2c_put_adapter(i2c_adap);
 	(...)
-}
+  }
 The above code instantiates up to 1 I2C device on the I2C bus which is on
 the OHCI adapter in question. It first tries at address 0x2c, if nothing
@@ -172,6 +173,7 @@ explicitly. Instead, i2c-core will probe for such devices as soon as their
 drivers are loaded, and if any is found, an I2C device will be
 instantiated automatically. In order to prevent any misbehavior of this
 mechanism, the following restrictions apply:
 * The I2C device driver must implement the detect() method, which
  identifies a supported device by reading from arbitrary registers.
 * Only buses which are likely to have a supported device and agree to be
@@ -189,6 +191,7 @@ first.
 Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6
 kernels will find out that this method 3 is essentially similar to what
 was done there. Two significant differences are:
 * Probing is only one way to instantiate I2C devices now, while it was the
  only way back then. Where possible, methods 1 and 2 should be preferred.
  Method 3 should only be used when there is no other way, as it can have
@@ -224,11 +227,13 @@ device. As no two devices can live at the same address on a given I2C
 segment, the address is sufficient to uniquely identify the device to be
 deleted.
-Example:
+Example::
-# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
+  # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
 While this interface should only be used when in-kernel device declaration
 can't be done, there is a variety of cases where it can be helpful:
 * The I2C driver usually detects devices (method 3 above) but the bus
  segment your device lives on doesn't have the proper class bit set and
  thus detection doesn't trigger.

--- a/Documentation/i2c/muxes/i2c-mux-gpio
+++ b/Documentation/i2c/muxes/i2c-mux-gpio
+==========================
 Kernel driver i2c-mux-gpio
+==========================
 Author: Peter Korsgaard <peter.korsgaard@barco.com>
@@ -8,7 +10,7 @@ Description
 i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments
 from a master I2C bus and a hardware MUX controlled through GPIO pins.
-E.G.:
+E.G.::
  ----------              ----------  Bus segment 1   - - - - -
 |          | SCL/SDA    |          |-------------- |           |
@@ -33,20 +35,20 @@ bus, the number of bus segments to create and the GPIO pins used
 to control it. See include/linux/platform_data/i2c-mux-gpio.h for details.
 E.G. something like this for a MUX providing 4 bus segments
-controlled through 3 GPIO pins:
+controlled through 3 GPIO pins::
-#include <linux/platform_data/i2c-mux-gpio.h>
+  #include <linux/platform_data/i2c-mux-gpio.h>
-#include <linux/platform_device.h>
+  #include <linux/platform_device.h>
-static const unsigned myboard_gpiomux_gpios[] = {
+  static const unsigned myboard_gpiomux_gpios[] = {
 	AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24
-};
+  };
-static const unsigned myboard_gpiomux_values[] = {
+  static const unsigned myboard_gpiomux_values[] = {
 	0, 1, 2, 3
-};
+  };
-static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
+  static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
 	.parent		= 1,
 	.base_nr	= 2, /* optional */
 	.values		= myboard_gpiomux_values,
@@ -54,15 +56,15 @@ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
 	.gpios		= myboard_gpiomux_gpios,
 	.n_gpios	= ARRAY_SIZE(myboard_gpiomux_gpios),
 	.idle		= 4, /* optional */
-};
+  };
-static struct platform_device myboard_i2cmux = {
+  static struct platform_device myboard_i2cmux = {
 	.name		= "i2c-mux-gpio",
 	.id		= 0,
 	.dev		= {
 		.platform_data	= &myboard_i2cmux_data,
 	},
-};
+  };
 If you don't know the absolute GPIO pin numbers at registration time,
 you can instead provide a chip name (.chip_name) and relative GPIO pin

--- a/Documentation/i2c/old-module-parameters
+++ b/Documentation/i2c/old-module-parameters
+=================================================
 I2C device driver binding control from user-space
 =================================================
@@ -19,23 +20,27 @@ Below is a mapping from the old module parameters to the new interface.
 Attaching a driver to an I2C device
 -----------------------------------
-Old method (module parameters):
+Old method (module parameters)::
-# modprobe <driver> probe=1,0x2d
-# modprobe <driver> force=1,0x2d
+  # modprobe <driver> probe=1,0x2d
-# modprobe <driver> force_<device>=1,0x2d
+  # modprobe <driver> force=1,0x2d
+  # modprobe <driver> force_<device>=1,0x2d
+New method (sysfs interface)::
-New method (sysfs interface):
+  # echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
-# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
 Preventing a driver from attaching to an I2C device
 ---------------------------------------------------
-Old method (module parameters):
+Old method (module parameters)::
-# modprobe <driver> ignore=1,0x2f
+  # modprobe <driver> ignore=1,0x2f
+New method (sysfs interface)::
-New method (sysfs interface):
+  # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
-# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
+  # modprobe <driver>
-# modprobe <driver>
 Of course, it is important to instantiate the "dummy" device before loading
 the driver. The dummy device will be handled by i2c-core itself, preventing

--- a/Documentation/i2c/slave-eeprom-backend
+++ b/Documentation/i2c/slave-eeprom-backend
+==============================
 Linux I2C slave eeprom backend
 ==============================
@@ -5,10 +6,9 @@ by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
 This is a proof-of-concept backend which acts like an EEPROM on the connected
 I2C bus. The memory contents can be modified from userspace via this file
-located in sysfs:
+located in sysfs::
 	/sys/bus/i2c/devices/<device-directory>/slave-eeprom
 As of 2015, Linux doesn't support poll on binary sysfs files, so there is no
 notification when another master changed the content.
--- a/Documentation/i2c/slave-interface
+++ b/Documentation/i2c/slave-interface
+=====================================
 Linux I2C slave interface description
 =====================================
@@ -12,7 +13,7 @@ EEPROM, the Linux I2C slave can access the content via sysfs and handle data as
 needed. The backend driver and the I2C bus driver communicate via events. Here
 is a small graph visualizing the data flow and the means by which data is
 transported. The dotted line marks only one example. The backend could also
-use a character device, be in-kernel only, or something completely different:
+use a character device, be in-kernel only, or something completely different::
              e.g. sysfs        I2C slave events        I/O registers
@@ -35,7 +36,7 @@ them as described in the document 'instantiating-devices'. The only difference
 is that i2c slave backends have their own address space. So, you have to add
 0x1000 to the address you would originally request. An example for
 instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64
-on bus 1:
+on bus 1::
  # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device
@@ -54,7 +55,7 @@ drivers and writing backends will be given.
 I2C slave events
 ----------------
-The bus driver sends an event to the backend using the following function:
+The bus driver sends an event to the backend using the following function::
 	ret = i2c_slave_event(client, event, &val)
@@ -69,8 +70,9 @@ Event types:
 * I2C_SLAVE_WRITE_REQUESTED (mandatory)
-'val': unused
+  'val': unused
-'ret': always 0
+  'ret': always 0
 Another I2C master wants to write data to us. This event should be sent once
 our own address and the write bit was detected. The data did not arrive yet, so
@@ -79,8 +81,9 @@ to be done, though.
 * I2C_SLAVE_READ_REQUESTED (mandatory)
-'val': backend returns first byte to be sent
+  'val': backend returns first byte to be sent
-'ret': always 0
+  'ret': always 0
 Another I2C master wants to read data from us. This event should be sent once
 our own address and the read bit was detected. After returning, the bus driver
@@ -88,8 +91,9 @@ should transmit the first byte.
 * I2C_SLAVE_WRITE_RECEIVED (mandatory)
-'val': bus driver delivers received byte
+  'val': bus driver delivers received byte
-'ret': 0 if the byte should be acked, some errno if the byte should be nacked
+  'ret': 0 if the byte should be acked, some errno if the byte should be nacked
 Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
 is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
@@ -97,8 +101,9 @@ should be nacked.
 * I2C_SLAVE_READ_PROCESSED (mandatory)
-'val': backend returns next byte to be sent
+  'val': backend returns next byte to be sent
-'ret': always 0
+  'ret': always 0
 The bus driver requests the next byte to be sent to another I2C master in
 'val'. Important: This does not mean that the previous byte has been acked, it
@@ -111,8 +116,9 @@ your backend, though.
 * I2C_SLAVE_STOP (mandatory)
-'val': unused
+  'val': unused
-'ret': always 0
+  'ret': always 0
 A stop condition was received. This can happen anytime and the backend should
 reset its state machine for I2C transfers to be able to receive new requests.
@@ -190,4 +196,3 @@ this time of writing. Some points to keep in mind when using buffers:
 * A master can send STOP at any time. For partially transferred buffers, this
  means additional code to handle this exception. Such code tends to be
  error-prone.
--- a/Documentation/i2c/smbus-protocol
+++ b/Documentation/i2c/smbus-protocol
+======================
 SMBus Protocol Summary
 ======================
@@ -27,12 +28,13 @@ Each transaction type corresponds to a functionality flag. Before calling a
 transaction function, a device driver should always check (just once) for
 the corresponding functionality flag to ensure that the underlying I2C
 adapter supports the transaction in question. See
-<file:Documentation/i2c/functionality> for the details.
+<file:Documentation/i2c/functionality.rst> for the details.
 Key to symbols
 ==============
+=============== =============================================================
 S     (1 bit) : Start bit
 P     (1 bit) : Stop bit
 Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
@@ -45,15 +47,17 @@ Data  (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
                for 16 bit data.
 Count (8 bits): A data byte containing the length of a block operation.
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
+[..]:           Data sent by I2C device, as opposed to data sent by the host
+                adapter.
+=============== =============================================================
 SMBus Quick Command
 ===================
-This sends a single bit to the device, at the place of the Rd/Wr bit.
+This sends a single bit to the device, at the place of the Rd/Wr bit::
-A Addr Rd/Wr [A] P
+  A Addr Rd/Wr [A] P
 Functionality flag: I2C_FUNC_SMBUS_QUICK
@@ -64,9 +68,9 @@ SMBus Receive Byte:  i2c_smbus_read_byte()
 This reads a single byte from a device, without specifying a device
 register. Some devices are so simple that this interface is enough; for
 others, it is a shorthand if you want to read the same register as in
-the previous SMBus command.
+the previous SMBus command::
-S Addr Rd [A] [Data] NA P
+  S Addr Rd [A] [Data] NA P
 Functionality flag: I2C_FUNC_SMBUS_READ_BYTE
@@ -77,7 +81,9 @@ SMBus Send Byte:  i2c_smbus_write_byte()
 This operation is the reverse of Receive Byte: it sends a single byte
 to a device.  See Receive Byte for more information.
-S Addr Wr [A] Data [A] P
+::
+  S Addr Wr [A] Data [A] P
 Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE
@@ -86,9 +92,9 @@ SMBus Read Byte:  i2c_smbus_read_byte_data()
 ============================================
 This reads a single byte from a device, from a designated register.
-The register is specified through the Comm byte.
+The register is specified through the Comm byte::
-S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
+  S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
 Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA
@@ -98,9 +104,9 @@ SMBus Read Word:  i2c_smbus_read_word_data()
 This operation is very like Read Byte; again, data is read from a
 device, from a designated register that is specified through the Comm
-byte. But this time, the data is a complete word (16 bits).
+byte. But this time, the data is a complete word (16 bits)::
-S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
+  S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
 Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA
@@ -116,7 +122,9 @@ This writes a single byte to a device, to a designated register. The
 register is specified through the Comm byte. This is the opposite of
 the Read Byte operation.
-S Addr Wr [A] Comm [A] Data [A] P
+::
+  S Addr Wr [A] Comm [A] Data [A] P
 Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA
@@ -126,9 +134,9 @@ SMBus Write Word:  i2c_smbus_write_word_data()
 This is the opposite of the Read Word operation. 16 bits
 of data is written to a device, to the designated register that is
-specified through the Comm byte. 
+specified through the Comm byte.::
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
+  S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
 Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA
@@ -141,9 +149,9 @@ SMBus Process Call:
 ===================
 This command selects a device register (through the Comm byte), sends
-16 bits of data to it, and reads 16 bits of data in return.
+16 bits of data to it, and reads 16 bits of data in return::
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] 
+  S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
                               S Addr Rd [A] [DataLow] A [DataHigh] NA P
 Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
@@ -156,7 +164,9 @@ This command reads a block of up to 32 bytes from a device, from a
 designated register that is specified through the Comm byte. The amount
 of data is specified by the device in the Count byte.
-S Addr Wr [A] Comm [A] 
+::
+  S Addr Wr [A] Comm [A]
             S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
 Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
@@ -169,7 +179,9 @@ The opposite of the Block Read command, this writes up to 32 bytes to
 a device, to a designated register that is specified through the
 Comm byte. The amount of data is specified in the Count byte.
-S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
+::
+  S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
 Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA
@@ -181,9 +193,9 @@ SMBus Block Write - Block Read Process Call was introduced in
 Revision 2.0 of the specification.
 This command selects a device register (through the Comm byte), sends
-1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return.
+1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return::
-S Addr Wr [A] Comm [A] Count [A] Data [A] ...
+  S Addr Wr [A] Comm [A] Count [A] Data [A] ...
                               S Addr Rd [A] [Count] A [Data] ... A P
 Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL
@@ -197,9 +209,12 @@ SMBus host acting as a slave.
 It is the same form as Write Word, with the command code replaced by the
 alerting device's address.
-[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
+::
+  [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
 This is implemented in the following way in the Linux kernel:
 * I2C bus drivers which support SMBus Host Notify should report
  I2C_FUNC_SMBUS_HOST_NOTIFY.
 * I2C bus drivers trigger SMBus Host Notify by a call to
@@ -241,6 +256,7 @@ single interrupt pin on the SMBus master, while still allowing the master
 to know which slave triggered the interrupt.
 This is implemented the following way in the Linux kernel:
 * I2C bus drivers which support SMBus alert should call
  i2c_setup_smbus_alert() to setup SMBus alert support.
 * I2C drivers for devices which can trigger SMBus alerts should implement
@@ -262,9 +278,9 @@ I2C Block Read:  i2c_smbus_read_i2c_block_data()
 ================================================
 This command reads a block of bytes from a device, from a
-designated register that is specified through the Comm byte.
+designated register that is specified through the Comm byte::
-S Addr Wr [A] Comm [A] 
+  S Addr Wr [A] Comm [A]
             S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
 Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
@@ -278,6 +294,8 @@ a device, to a designated register that is specified through the
 Comm byte. Note that command lengths of 0, 2, or more bytes are
 supported as they are indistinguishable from data.
-S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
+::
+  S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
 Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK
--- a/Documentation/i2c/summary
+++ b/Documentation/i2c/summary
+=============
 I2C and SMBus
 =============
@@ -24,7 +25,8 @@ implement all the common SMBus protocol semantics or messages.
 Terminology
 ===========
-When we talk about I2C, we use the following terms:
+When we talk about I2C, we use the following terms::
  Bus    -> Algorithm
            Adapter
  Device -> Driver

--- a/Documentation/i2c/ten-bit-addresses
+++ b/Documentation/i2c/ten-bit-addresses
+=====================
+I2C Ten-bit Addresses
+=====================
 The I2C protocol knows about two kinds of device addresses: normal 7 bit
 addresses, and an extended set of 10 bit addresses. The sets of addresses
 do not intersect: the 7 bit address 0x10 is not the same as the 10 bit
@@ -12,6 +16,7 @@ See the I2C specification for the details.
 The current 10 bit address support is minimal. It should work, however
 you can expect some problems along the way:
 * Not all bus drivers support 10-bit addresses. Some don't because the
  hardware doesn't support them (SMBus doesn't require 10-bit address
  support for example), some don't because nobody bothered adding the

--- a/Documentation/i2c/upgrading-clients
+++ b/Documentation/i2c/upgrading-clients
+=================================================
 Upgrading I2C Drivers to the new 2.6 Driver Model
 =================================================
@@ -13,21 +14,22 @@ the old to the new new binding methods.
 Example old-style driver
 ------------------------
+::
-struct example_state {
+  struct example_state {
 	struct i2c_client	client;
 	....
-};
+  };
-static struct i2c_driver example_driver;
+  static struct i2c_driver example_driver;
-static unsigned short ignore[] = { I2C_CLIENT_END };
+  static unsigned short ignore[] = { I2C_CLIENT_END };
-static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+  static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
-I2C_CLIENT_INSMOD;
+  I2C_CLIENT_INSMOD;
-static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+  static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-{
+  {
 	struct example_state *state;
 	struct device *dev = &adap->dev;  /* to use for dev_ reports */
 	int ret;
@@ -59,23 +61,23 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind)
 	dev_info(dev, "example client created\n");
 	return 0;
-}
+  }
-static int example_detach(struct i2c_client *client)
+  static int example_detach(struct i2c_client *client)
-{
+  {
 	struct example_state *state = i2c_get_clientdata(client);
 	i2c_detach_client(client);
 	kfree(state);
 	return 0;
-}
+  }
-static int example_attach_adapter(struct i2c_adapter *adap)
+  static int example_attach_adapter(struct i2c_adapter *adap)
-{
+  {
 	return i2c_probe(adap, &addr_data, example_attach);
-}
+  }
-static struct i2c_driver example_driver = {
+  static struct i2c_driver example_driver = {
 	.driver		= {
 		.owner		= THIS_MODULE,
 		.name		= "example",
@@ -83,7 +85,7 @@ static struct i2c_driver example_driver = {
 	},
 	.attach_adapter = example_attach_adapter,
 	.detach_client	= example_detach,
-};
+  };
 Updating the client
@@ -93,38 +95,38 @@ The new style binding model will check against a list of supported
 devices and their associated address supplied by the code registering
 the busses. This means that the driver .attach_adapter and
 .detach_client methods can be removed, along with the addr_data,
-as follows:
+as follows::
- static struct i2c_driver example_driver;
+  - static struct i2c_driver example_driver;
- static unsigned short ignore[] = { I2C_CLIENT_END };
+  - static unsigned short ignore[] = { I2C_CLIENT_END };
- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+  - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
- I2C_CLIENT_INSMOD;
+  - I2C_CLIENT_INSMOD;
- static int example_attach_adapter(struct i2c_adapter *adap)
+  - static int example_attach_adapter(struct i2c_adapter *adap)
- {
+  - {
- 	return i2c_probe(adap, &addr_data, example_attach);
+  - 	return i2c_probe(adap, &addr_data, example_attach);
- }
+  - }
    static struct i2c_driver example_driver = {
-	.attach_adapter = example_attach_adapter,
+  -	.attach_adapter = example_attach_adapter,
-	.detach_client	= example_detach,
+  -	.detach_client	= example_detach,
    }
-Add the probe and remove methods to the i2c_driver, as so:
+Add the probe and remove methods to the i2c_driver, as so::
   static struct i2c_driver example_driver = {
-+	.probe		= example_probe,
+  +	.probe		= example_probe,
-+	.remove		= example_remove,
+  +	.remove		= example_remove,
   }
 Change the example_attach method to accept the new parameters
-which include the i2c_client that it will be working with:
+which include the i2c_client that it will be working with::
- static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+  - static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-+ static int example_probe(struct i2c_client *client,
+  + static int example_probe(struct i2c_client *client,
-+			   const struct i2c_device_id *id)
+  +			   const struct i2c_device_id *id)
 Change the name of example_attach to example_probe to align it with the
 i2c_driver entry names. The rest of the probe routine will now need to be
@@ -132,55 +134,57 @@ changed as the i2c_client has already been setup for use.
 The necessary client fields have already been setup before
 the probe function is called, so the following client setup
-can be removed:
+can be removed::
-	example->client.addr    = addr;
+  -	example->client.addr    = addr;
-	example->client.flags   = 0;
+  -	example->client.flags   = 0;
-	example->client.adapter = adap;
+  -	example->client.adapter = adap;
-
+  -
-	strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
+  -	strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
-The i2c_set_clientdata is now:
+The i2c_set_clientdata is now::
-	i2c_set_clientdata(&state->client, state);
+  -	i2c_set_clientdata(&state->client, state);
-+	i2c_set_clientdata(client, state);
+  +	i2c_set_clientdata(client, state);
 The call to i2c_attach_client is no longer needed, if the probe
 routine exits successfully, then the driver will be automatically
-attached by the core. Change the probe routine as so:
+attached by the core. Change the probe routine as so::
-	ret = i2c_attach_client(&state->i2c_client);
+  -	ret = i2c_attach_client(&state->i2c_client);
-	if (ret < 0) {
+  -	if (ret < 0) {
-		dev_err(dev, "failed to attach client\n");
+  -		dev_err(dev, "failed to attach client\n");
-		kfree(state);
+  -		kfree(state);
-		return ret;
+  -		return ret;
-	}
+  -	}
 Remove the storage of 'struct i2c_client' from the 'struct example_state'
 as we are provided with the i2c_client in our example_probe. Instead we
 store a pointer to it for when it is needed.
-struct example_state {
+::
-	struct i2c_client	client;
-+	struct i2c_client	*client;
+  struct example_state {
+  -	struct i2c_client	client;
+  +	struct i2c_client	*client;
-the new i2c client as so:
+the new i2c client as so::
-	struct device *dev = &adap->dev;  /* to use for dev_ reports */
+  -	struct device *dev = &adap->dev;  /* to use for dev_ reports */
-+ 	struct device *dev = &i2c_client->dev;  /* to use for dev_ reports */
+  + 	struct device *dev = &i2c_client->dev;  /* to use for dev_ reports */
 And remove the change after our client is attached, as the driver no
-longer needs to register a new client structure with the core:
+longer needs to register a new client structure with the core::
-	dev = &state->i2c_client.dev;
+  -	dev = &state->i2c_client.dev;
 In the probe routine, ensure that the new state has the client stored
-in it:
+in it::
-static int example_probe(struct i2c_client *i2c_client,
+  static int example_probe(struct i2c_client *i2c_client,
 			 const struct i2c_device_id *id)
-{
+  {
 	struct example_state *state;
 	struct device *dev = &i2c_client->dev;
 	int ret;
@@ -191,48 +195,50 @@ static int example_probe(struct i2c_client *i2c_client,
 		return -ENOMEM;
 	}
-+	state->client = i2c_client;
+  +	state->client = i2c_client;
 Update the detach method, by changing the name to _remove and
 to delete the i2c_detach_client call. It is possible that you
 can also remove the ret variable as it is not needed for any
 of the core functions.
- static int example_detach(struct i2c_client *client)
+::
-+ static int example_remove(struct i2c_client *client)
-{
+  - static int example_detach(struct i2c_client *client)
+  + static int example_remove(struct i2c_client *client)
+  {
 	struct example_state *state = i2c_get_clientdata(client);
-	i2c_detach_client(client);
+  -	i2c_detach_client(client);
 And finally ensure that we have the correct ID table for the i2c-core
-and other utilities:
+and other utilities::
-+ struct i2c_device_id example_idtable[] = {
+  + struct i2c_device_id example_idtable[] = {
-+       { "example", 0 },
+  +       { "example", 0 },
-+       { }
+  +       { }
-+};
+  +};
-+
+  +
-+MODULE_DEVICE_TABLE(i2c, example_idtable);
+  +MODULE_DEVICE_TABLE(i2c, example_idtable);
-static struct i2c_driver example_driver = {
+  static struct i2c_driver example_driver = {
 	.driver		= {
 		.owner		= THIS_MODULE,
 		.name		= "example",
 	},
-+	.id_table	= example_ids,
+  +	.id_table	= example_ids,
-Our driver should now look like this:
+Our driver should now look like this::
-struct example_state {
+  struct example_state {
 	struct i2c_client	*client;
 	....
-};
+  };
-static int example_probe(struct i2c_client *client,
+  static int example_probe(struct i2c_client *client,
 			 const struct i2c_device_id *id)
-{
+  {
 	struct example_state *state;
 	struct device *dev = &client->dev;
@@ -250,24 +256,24 @@ static int example_probe(struct i2c_client *client,
 	dev_info(dev, "example client created\n");
 	return 0;
-}
+  }
-static int example_remove(struct i2c_client *client)
+  static int example_remove(struct i2c_client *client)
-{
+  {
 	struct example_state *state = i2c_get_clientdata(client);
 	kfree(state);
 	return 0;
-}
+  }
-static struct i2c_device_id example_idtable[] = {
+  static struct i2c_device_id example_idtable[] = {
 	{ "example", 0 },
 	{ }
-};
+  };
-MODULE_DEVICE_TABLE(i2c, example_idtable);
+  MODULE_DEVICE_TABLE(i2c, example_idtable);
-static struct i2c_driver example_driver = {
+  static struct i2c_driver example_driver = {
 	.driver		= {
 		.owner		= THIS_MODULE,
 		.name		= "example",
@@ -276,4 +282,4 @@ static struct i2c_driver example_driver = {
 	.id_table	= example_idtable,
 	.probe		= example_probe,
 	.remove		= example_remove,
-};
+  };
--- a/Documentation/i2c/writing-clients
+++ b/Documentation/i2c/writing-clients
+===================
+Writing I2C Clients
+===================
 This is a small guide for those who want to write kernel drivers for I2C
 or SMBus devices, using Linux as the protocol host/master (not slave).
@@ -12,7 +16,7 @@ General remarks
 Try to keep the kernel namespace as clean as possible. The best way to
 do this is to use a unique prefix for all global symbols. This is
 especially important for exported symbols, but it is a good idea to do
-it for non-exported symbols too. We will use the prefix `foo_' in this
+it for non-exported symbols too. We will use the prefix ``foo_`` in this
 tutorial.
@@ -25,15 +29,17 @@ routines, and should be zero-initialized except for fields with data you
 provide.  A client structure holds device-specific information like the
 driver model device node, and its I2C address.
-static struct i2c_device_id foo_idtable[] = {
+::
+  static struct i2c_device_id foo_idtable[] = {
 	{ "foo", my_id_for_foo },
 	{ "bar", my_id_for_bar },
 	{ }
-};
+  };
-MODULE_DEVICE_TABLE(i2c, foo_idtable);
+  MODULE_DEVICE_TABLE(i2c, foo_idtable);
-static struct i2c_driver foo_driver = {
+  static struct i2c_driver foo_driver = {
 	.driver = {
 		.name	= "foo",
 		.pm	= &foo_pm_ops,	/* optional */
@@ -49,7 +55,7 @@ static struct i2c_driver foo_driver = {
 	.shutdown	= foo_shutdown,	/* optional */
 	.command	= foo_command,	/* optional, deprecated */
-}
+  }
 The name field is the driver name, and must not contain spaces.  It
 should match the module name (if the driver can be compiled as a module),
@@ -64,16 +70,18 @@ below.
 Extra client data
 =================
-Each client structure has a special `data' field that can point to any
+Each client structure has a special ``data`` field that can point to any
 structure at all.  You should use this to keep device-specific data.
+::
 	/* store the value */
 	void i2c_set_clientdata(struct i2c_client *client, void *data);
 	/* retrieve the value */
 	void *i2c_get_clientdata(const struct i2c_client *client);
-Note that starting with kernel 2.6.34, you don't have to set the `data' field
+Note that starting with kernel 2.6.34, you don't have to set the ``data`` field
 to NULL in remove() or if probe() failed anymore. The i2c-core does this
 automatically on these occasions. Those are also the only times the core will
 touch this field.
@@ -92,25 +100,25 @@ but many chips have some kind of register-value idea that can easily
 be encapsulated.
 The below functions are simple examples, and should not be copied
-literally.
+literally::
-int foo_read_value(struct i2c_client *client, u8 reg)
+  int foo_read_value(struct i2c_client *client, u8 reg)
-{
+  {
 	if (reg < 0x10)	/* byte-sized register */
 		return i2c_smbus_read_byte_data(client, reg);
 	else		/* word-sized register */
 		return i2c_smbus_read_word_data(client, reg);
-}
+  }
-int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
+  int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
-{
+  {
 	if (reg == 0x10)	/* Impossible to write - driver error! */
 		return -EINVAL;
 	else if (reg < 0x10)	/* byte-sized register */
 		return i2c_smbus_write_byte_data(client, reg, value);
 	else			/* word-sized register */
 		return i2c_smbus_write_word_data(client, reg, value);
-}
+  }
 Probing and attaching
@@ -145,6 +153,8 @@ I2C device drivers using this binding model work just like any other
 kind of driver in Linux:  they provide a probe() method to bind to
 those devices, and a remove() method to unbind.
+::
 	static int foo_probe(struct i2c_client *client,
 			     const struct i2c_device_id *id);
 	static int foo_remove(struct i2c_client *client);
@@ -240,37 +250,41 @@ When the kernel is booted, or when your foo driver module is inserted,
 you have to do some initializing. Fortunately, just registering the
 driver module is usually enough.
-static int __init foo_init(void)
+::
-{
+  static int __init foo_init(void)
+  {
 	return i2c_add_driver(&foo_driver);
-}
+  }
-module_init(foo_init);
+  module_init(foo_init);
-static void __exit foo_cleanup(void)
+  static void __exit foo_cleanup(void)
-{
+  {
 	i2c_del_driver(&foo_driver);
-}
+  }
-module_exit(foo_cleanup);
+  module_exit(foo_cleanup);
-The module_i2c_driver() macro can be used to reduce above code.
+  The module_i2c_driver() macro can be used to reduce above code.
-module_i2c_driver(foo_driver);
+  module_i2c_driver(foo_driver);
-Note that some functions are marked by `__init'.  These functions can
+Note that some functions are marked by ``__init``.  These functions can
 be removed after kernel booting (or module loading) is completed.
-Likewise, functions marked by `__exit' are dropped by the compiler when
+Likewise, functions marked by ``__exit`` are dropped by the compiler when
 the code is built into the kernel, as they would never be called.
 Driver Information
 ==================
-/* Substitute your own name and email address */
+::
-MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
-MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
-/* a few non-GPL license types are also allowed */
+  /* Substitute your own name and email address */
-MODULE_LICENSE("GPL");
+  MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
+  MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+  /* a few non-GPL license types are also allowed */
+  MODULE_LICENSE("GPL");
 Power Management
@@ -323,6 +337,8 @@ commands, but only some of them understand plain I2C!
 Plain I2C communication
 -----------------------
+::
 	int i2c_master_send(struct i2c_client *client, const char *buf,
 			    int count);
 	int i2c_master_recv(struct i2c_client *client, char *buf, int count);
@@ -334,6 +350,8 @@ to read/write (must be less than the length of the buffer, also should be
 less than 64k since msg.len is u16.) Returned is the actual number of bytes
 read/written.
+::
 	int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
 			 int num);
@@ -343,13 +361,15 @@ stop bit is sent between transaction. The i2c_msg structure contains
 for each message the client address, the number of bytes of the message
 and the message data itself.
-You can read the file `i2c-protocol' for more information about the
+You can read the file ``i2c-protocol`` for more information about the
 actual I2C protocol.
 SMBus communication
 -------------------
+::
 	s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
 			   unsigned short flags, char read_write, u8 command,
 			   int size, union i2c_smbus_data *data);
@@ -357,6 +377,8 @@ SMBus communication
 This is the generic SMBus function. All functions below are implemented
 in terms of it. Never use this function directly!
+::
 	s32 i2c_smbus_read_byte(struct i2c_client *client);
 	s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);
 	s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);
@@ -376,7 +398,7 @@ in terms of it. Never use this function directly!
 					   const u8 *values);
 These ones were removed from i2c-core because they had no users, but could
-be added back later if needed:
+be added back later if needed::
 	s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);
 	s32 i2c_smbus_process_call(struct i2c_client *client,
@@ -389,7 +411,7 @@ transactions return 0 on success; the 'read' transactions return the read
 value, except for block transactions, which return the number of values
 read. The block buffers need not be longer than 32 bytes.
-You can read the file `smbus-protocol' for more information about the
+You can read the file ``smbus-protocol`` for more information about the
 actual SMBus protocol.
@@ -397,7 +419,7 @@ General purpose routines
 ========================
 Below all general purpose routines are listed, that were not mentioned
-before.
+before::
 	/* Return the adapter number for a specific adapter */
 	int i2c_adapter_id(struct i2c_adapter *adap);
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -104,6 +104,7 @@ needed).
   fb/index
   fpga/index
   hid/index
+   i2c/index
   iio/index
   infiniband/index
   leds/index

--- a/Documentation/spi/spi-sc18is602
+++ b/Documentation/spi/spi-sc18is602
@@ -17,7 +17,7 @@ kernel's SPI core subsystem.
 The driver does not probe for supported chips, since the SI18IS602/603 does not
 support Chip ID registers. You will have to instantiate the devices explicitly.
-Please see Documentation/i2c/instantiating-devices for details.
+Please see Documentation/i2c/instantiating-devices.rst for details.
 Usage Notes

--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -666,7 +666,7 @@ ALI1563 I2C DRIVER
 M:	Rudolf Marek <r.marek@assembler.cz>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/busses/i2c-ali1563
+F:	Documentation/i2c/busses/i2c-ali1563.rst
 F:	drivers/i2c/busses/i2c-ali1563.c
 ALLEGRO DVT VIDEO IP CORE DRIVER
@@ -6741,7 +6741,7 @@ L:	linux-i2c@vger.kernel.org
 S:	Supported
 F:	drivers/i2c/muxes/i2c-mux-gpio.c
 F:	include/linux/platform_data/i2c-mux-gpio.h
-F:	Documentation/i2c/muxes/i2c-mux-gpio
+F:	Documentation/i2c/muxes/i2c-mux-gpio.rst
 GENERIC HDLC (WAN) DRIVERS
 M:	Krzysztof Halasa <khc@pm.waw.pl>
@@ -7497,14 +7497,14 @@ I2C CONTROLLER DRIVER FOR NVIDIA GPU
 M:	Ajay Gupta <ajayg@nvidia.com>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/busses/i2c-nvidia-gpu
+F:	Documentation/i2c/busses/i2c-nvidia-gpu.rst
 F:	drivers/i2c/busses/i2c-nvidia-gpu.c
 I2C MUXES
 M:	Peter Rosin <peda@axentia.se>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/i2c-topology
+F:	Documentation/i2c/i2c-topology.rst
 F:	Documentation/i2c/muxes/
 F:	Documentation/devicetree/bindings/i2c/i2c-mux*
 F:	Documentation/devicetree/bindings/i2c/i2c-arb*
@@ -7524,8 +7524,8 @@ I2C OVER PARALLEL PORT
 M:	Jean Delvare <jdelvare@suse.com>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/busses/i2c-parport
+F:	Documentation/i2c/busses/i2c-parport.rst
-F:	Documentation/i2c/busses/i2c-parport-light
+F:	Documentation/i2c/busses/i2c-parport-light.rst
 F:	drivers/i2c/busses/i2c-parport.c
 F:	drivers/i2c/busses/i2c-parport-light.c
@@ -7559,7 +7559,7 @@ I2C-TAOS-EVM DRIVER
 M:	Jean Delvare <jdelvare@suse.com>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/busses/i2c-taos-evm
+F:	Documentation/i2c/busses/i2c-taos-evm.rst
 F:	drivers/i2c/busses/i2c-taos-evm.c
 I2C-TINY-USB DRIVER
@@ -7573,19 +7573,19 @@ I2C/SMBUS CONTROLLER DRIVERS FOR PC
 M:	Jean Delvare <jdelvare@suse.com>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/busses/i2c-ali1535
+F:	Documentation/i2c/busses/i2c-ali1535.rst
-F:	Documentation/i2c/busses/i2c-ali1563
+F:	Documentation/i2c/busses/i2c-ali1563.rst
-F:	Documentation/i2c/busses/i2c-ali15x3
+F:	Documentation/i2c/busses/i2c-ali15x3.rst
-F:	Documentation/i2c/busses/i2c-amd756
+F:	Documentation/i2c/busses/i2c-amd756.rst
-F:	Documentation/i2c/busses/i2c-amd8111
+F:	Documentation/i2c/busses/i2c-amd8111.rst
-F:	Documentation/i2c/busses/i2c-i801
+F:	Documentation/i2c/busses/i2c-i801.rst
-F:	Documentation/i2c/busses/i2c-nforce2
+F:	Documentation/i2c/busses/i2c-nforce2.rst
-F:	Documentation/i2c/busses/i2c-piix4
+F:	Documentation/i2c/busses/i2c-piix4.rst
-F:	Documentation/i2c/busses/i2c-sis5595
+F:	Documentation/i2c/busses/i2c-sis5595.rst
-F:	Documentation/i2c/busses/i2c-sis630
+F:	Documentation/i2c/busses/i2c-sis630.rst
-F:	Documentation/i2c/busses/i2c-sis96x
+F:	Documentation/i2c/busses/i2c-sis96x.rst
-F:	Documentation/i2c/busses/i2c-via
+F:	Documentation/i2c/busses/i2c-via.rst
-F:	Documentation/i2c/busses/i2c-viapro
+F:	Documentation/i2c/busses/i2c-viapro.rst
 F:	drivers/i2c/busses/i2c-ali1535.c
 F:	drivers/i2c/busses/i2c-ali1563.c
 F:	drivers/i2c/busses/i2c-ali15x3.c
@@ -7614,7 +7614,7 @@ M:	Seth Heasley <seth.heasley@intel.com>
 M:	Neil Horman <nhorman@tuxdriver.com>
 L:	linux-i2c@vger.kernel.org
 F:	drivers/i2c/busses/i2c-ismt.c
-F:	Documentation/i2c/busses/i2c-ismt
+F:	Documentation/i2c/busses/i2c-ismt.rst
 I2C/SMBUS STUB DRIVER
 M:	Jean Delvare <jdelvare@suse.com>
@@ -10355,7 +10355,7 @@ L:	linux-i2c@vger.kernel.org
 S:	Supported
 F:	drivers/i2c/busses/i2c-mlxcpld.c
 F:	drivers/i2c/muxes/i2c-mux-mlxcpld.c
-F:	Documentation/i2c/busses/i2c-mlxcpld
+F:	Documentation/i2c/busses/i2c-mlxcpld.rst
 MELLANOX MLXCPLD LED DRIVER
 M:	Vadim Pasternak <vadimp@mellanox.com>
@@ -11976,7 +11976,7 @@ M:	Andrew Lunn <andrew@lunn.ch>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
 F:	Documentation/devicetree/bindings/i2c/i2c-ocores.txt
-F:	Documentation/i2c/busses/i2c-ocores
+F:	Documentation/i2c/busses/i2c-ocores.rst
 F:	drivers/i2c/busses/i2c-ocores.c
 F:	include/linux/platform_data/i2c-ocores.h
@@ -14280,7 +14280,7 @@ F:	net/sctp/
 SCx200 CPU SUPPORT
 M:	Jim Cromie <jim.cromie@gmail.com>
 S:	Odd Fixes
-F:	Documentation/i2c/busses/scx200_acb
+F:	Documentation/i2c/busses/scx200_acb.rst
 F:	arch/x86/platform/scx200/
 F:	drivers/watchdog/scx200_wdt.c
 F:	drivers/i2c/busses/scx200*

--- a/drivers/hwmon/atxp1.c
+++ b/drivers/hwmon/atxp1.c
@@ -5,7 +5,7 @@
 *
 * The ATXP1 can reside on I2C addresses 0x37 or 0x4e. The chip is
 * not auto-detected by the driver and must be instantiated explicitly.
- * See Documentation/i2c/instantiating-devices for more information.
+ * See Documentation/i2c/instantiating-devices.rst for more information.
 */
 #include <linux/kernel.h>

--- a/drivers/hwmon/smm665.c
+++ b/drivers/hwmon/smm665.c
@@ -197,7 +197,7 @@ static int smm665_read_adc(struct smm665_data *data, int adc)
 	if (rv != -ENXIO) {
 		/*
 		 * We expect ENXIO to reflect NACK
-		 * (per Documentation/i2c/fault-codes).
+		 * (per Documentation/i2c/fault-codes.rst).
 		 * Everything else is an error.
 		 */
 		dev_dbg(&client->dev,

--- a/drivers/i2c/Kconfig
+++ b/drivers/i2c/Kconfig
@@ -54,7 +54,7 @@ config I2C_CHARDEV
 	  Say Y here to use i2c-* device files, usually found in the /dev
 	  directory on your system.  They make it possible to have user-space
 	  programs use the I2C bus.  Information on how to do this is
-	  contained in the file <file:Documentation/i2c/dev-interface>.
+	  contained in the file <file:Documentation/i2c/dev-interface.rst>.
 	  This support is also available as a module.  If so, the module 
 	  will be called i2c-dev.
@@ -107,7 +107,7 @@ config I2C_STUB
 	  especially for certain kinds of sensor chips.
 	  If you do build this module, be sure to read the notes and warnings
-	  in <file:Documentation/i2c/i2c-stub>.
+	  in <file:Documentation/i2c/i2c-stub.rst>.
 	  If you don't know what to do here, definitely say N.

--- a/drivers/i2c/busses/Kconfig
+++ b/drivers/i2c/busses/Kconfig
@@ -1206,7 +1206,7 @@ config I2C_PARPORT
 	  and makes it easier to add support for new devices.
 	  An adapter type parameter is now mandatory.  Please read the file
-	  Documentation/i2c/busses/i2c-parport for details.
+	  Documentation/i2c/busses/i2c-parport.rst for details.
 	  Another driver exists, named i2c-parport-light, which doesn't depend
 	  on the parport driver.  This is meant for embedded systems. Don't say

--- a/drivers/i2c/busses/i2c-i801.c
+++ b/drivers/i2c/busses/i2c-i801.c
@@ -77,7 +77,7 @@
 * SMBus Host Notify			yes
 * Interrupt processing			yes
 *
- * See the file Documentation/i2c/busses/i2c-i801 for details.
+ * See the file Documentation/i2c/busses/i2c-i801.rst for details.
 */
 #include <linux/interrupt.h>

--- a/drivers/i2c/busses/i2c-taos-evm.c
+++ b/drivers/i2c/busses/i2c-taos-evm.c
@@ -125,7 +125,7 @@ static int taos_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
 			/*
 			 * Voluntarily dropping error code of kstrtou8 since all
 			 * error code that it could return are invalid according
-			 * to Documentation/i2c/fault-codes.
+			 * to Documentation/i2c/fault-codes.rst.
 			 */
 			if (kstrtou8(p + 1, 16, &data->byte))
 				return -EPROTO;

--- a/drivers/i2c/i2c-core-base.c
+++ b/drivers/i2c/i2c-core-base.c
@@ -2206,7 +2206,7 @@ static int i2c_detect_address(struct i2c_client *temp_client,
 			dev_warn(&adapter->dev,
 				"This adapter will soon drop class based instantiation of devices. "
 				"Please make sure client 0x%02x gets instantiated by other means. "
-				"Check 'Documentation/i2c/instantiating-devices' for details.\n",
+				"Check 'Documentation/i2c/instantiating-devices.rst' for details.\n",
 				info.addr);
 		dev_dbg(&adapter->dev, "Creating %s at 0x%02x\n",
@@ -2236,7 +2236,7 @@ static int i2c_detect(struct i2c_adapter *adapter, struct i2c_driver *driver)
 	if (adapter->class == I2C_CLASS_DEPRECATED) {
 		dev_dbg(&adapter->dev,
 			"This adapter dropped support for I2C classes and won't auto-detect %s devices anymore. "
-			"If you need it, check 'Documentation/i2c/instantiating-devices' for alternatives.\n",
+			"If you need it, check 'Documentation/i2c/instantiating-devices.rst' for alternatives.\n",
 			driver->driver.name);
 		return 0;
 	}

--- a/drivers/iio/dummy/iio_simple_dummy.c
+++ b/drivers/iio/dummy/iio_simple_dummy.c
@@ -693,7 +693,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
 * Varies depending on bus type of the device. As there is no device
 * here, call probe directly. For information on device registration
 * i2c:
- * Documentation/i2c/writing-clients
+ * Documentation/i2c/writing-clients.rst
 * spi:
 * Documentation/spi/spi-summary
 */

--- a/drivers/rtc/rtc-ds1374.c
+++ b/drivers/rtc/rtc-ds1374.c
@@ -14,7 +14,7 @@
 */
 /*
 * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
- * recommened in .../Documentation/i2c/writing-clients section
+ * recommended in .../Documentation/i2c/writing-clients.rst section
 * "Sending and receiving", using SMBus level communication is preferred.
 */

--- a/include/linux/i2c.h
+++ b/include/linux/i2c.h
@@ -521,7 +521,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
 *
 * The return codes from the @master_xfer{_atomic} fields should indicate the
 * type of error code that occurred during the transfer, as documented in the
- * Kernel Documentation file Documentation/i2c/fault-codes.
+ * Kernel Documentation file Documentation/i2c/fault-codes.rst.
 */
 struct i2c_algorithm {
 	/*