linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 00/26] docs: i2c: rework I2C documentation, part I
@ 2020-01-05 22:39 Luca Ceresoli
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                   ` (4 more replies)
  0 siblings, 5 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:39 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Hi,

this series is a list of improvements to the I2C documentation.

It started as a simple reordering of index.rst from alphabetical order to a
logical order. Then it grew to a mixture of various improvements to each
section. I wanted to rework all the sections in a unique series, but after
covering about one third of them the number of patches has already grown
pretty long so I'm sending it in its current state.

Let's see how this series is received, I will continue to cover the rest of
the sections later.

Each patch is quite self-standing, and most are trivial, so have a good
reading.

Luca

Luca Ceresoli (26):
  docs: i2c: sort index logically
  docs: i2c: summary: extend introduction
  docs: i2c: summary: rewrite the "terminology" section
  docs: i2c: call it "I2C" consistently
  docs: i2c: fix typo
  docs: i2c: replace "I2C-transfer" -> "I2C transfer" consistently
  docs: i2c: i2c-protocol: fix kernel-doc function syntax
  docs: i2c: i2c-protocol: properly name start and stop conditions
  docs: i2c: i2c-protocol: remove unneeded colons from table
  docs: i2c: i2c-protocol: use proper names for ACK and NACK
  docs: i2c: smbus: fix link syntax
  docs: i2c: smbus-protocol: properly name start and stop conditions
  docs: i2c: smbus-protocol: remove unneeded colons from table
  docs: i2c: smbus-protocol: use proper names for ACK and NACK
  docs: i2c: smbus-protocol: enable kernel-doc function syntax
  docs: i2c: smbus-protocol: fix kernel-doc function syntax
  docs: i2c: i2c-protocol: fix typo
  docs: i2c: i2c-protocol: fix punctuation
  docs: i2c: smbus-protocol: improve I2C Block transactions description
  docs: i2c: instantiating-devices: fix internal hyperlink
  docs: i2c: instantiating-devices: rearrange static instatiation
  docs: i2c: instantiating-devices: use monospace for filenames
  docs: i2c: old-module-parameters: fix internal hyperlink
  docs: i2c: old-module-parameters: clarify this is for obsolete kernels
  docs: i2c: old-module-parameters: use monospace for filenames
  docs: i2c: rename sections so the overall picture is clearer

 Documentation/i2c/dev-interface.rst         |   24 +-
 Documentation/i2c/dma-considerations.rst    |    2 +-
 Documentation/i2c/i2c-protocol.rst          |   45 +-
 Documentation/i2c/i2c-topology.rst          |   72 +-
 Documentation/i2c/i2c.svg                   | 1341 +++++++++++++++++++
 Documentation/i2c/index.rst                 |   21 +-
 Documentation/i2c/instantiating-devices.rst |  116 +-
 Documentation/i2c/old-module-parameters.rst |   30 +-
 Documentation/i2c/slave-interface.rst       |    4 +-
 Documentation/i2c/smbus-protocol.rst        |  107 +-
 Documentation/i2c/summary.rst               |   61 +-
 Documentation/i2c/writing-clients.rst       |   10 +-
 12 files changed, 1611 insertions(+), 222 deletions(-)
 create mode 100644 Documentation/i2c/i2c.svg

-- 
2.24.1


^ permalink raw reply	[flat|nested] 72+ messages in thread

* [PATCH 01/26] docs: i2c: sort index logically
  2020-01-05 22:39 [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
@ 2020-01-05 22:49 ` Luca Ceresoli
  2020-01-05 22:49   ` [PATCH 02/26] docs: i2c: summary: extend introduction Luca Ceresoli
                     ` (22 more replies)
  2020-01-06  7:46 ` [PATCH 24/26] docs: i2c: old-module-parameters: clarify this is for obsolete kernels Luca Ceresoli
                   ` (3 subsequent siblings)
  4 siblings, 23 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

The index page currently lists sections in alphabetical file order without
caring about their content. Sort sections based on their content logically,
according to the following structure:

 * Intro to I2C/SMBus and their usage in Linux: summary, i2c-protocol,
   smbus-protocol, instantiating-devices, busses/index, i2c-topology,
   muxes/i2c-mux-gpio
 * Implementing drivers: writing-clients, dev-interface,
   dma-considerations, fault-codes, functionality
 * Debugging: gpio-fault-injection, i2c-stub
 * Slave I2C: slave-interface, slave-eeprom-backend
 * Advanced: ten-bit-addresses
 * Obsolete info: upgrading-clients, old-module-parameters

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/index.rst | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
index a0fbaf6d0675..bd0ff9d00793 100644
--- a/Documentation/i2c/index.rst
+++ b/Documentation/i2c/index.rst
@@ -7,27 +7,26 @@ I2C/SMBus Subsystem
 .. toctree::
    :maxdepth: 1
 
+   summary
+   i2c-protocol
+   smbus-protocol
+   instantiating-devices
+   busses/index
+   i2c-topology
+   muxes/i2c-mux-gpio
+   writing-clients
    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
+   slave-eeprom-backend
    ten-bit-addresses
    upgrading-clients
-   writing-clients
-
-   muxes/i2c-mux-gpio
+   old-module-parameters
 
-   busses/index
 
 .. only::  subproject and html
 
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 02/26] docs: i2c: summary: extend introduction
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-20  9:27     ` Jean Delvare
  2020-01-05 22:49   ` [PATCH 03/26] docs: i2c: summary: rewrite the "terminology" section Luca Ceresoli
                     ` (21 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

 - state the "official" name (I²C, not I2C, according to the spec) at
   the beginning but keep using the more practical I2C elsewhere
 - mention some known different names
 - add link to the specification document

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/summary.rst | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
index 3a24eac17375..b7d3e620155b 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -2,12 +2,18 @@
 I2C and SMBus
 =============
 
-I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
-slow two-wire protocol (variable speed, up to 400 kHz), with a high speed
-extension (3.4 MHz).  It provides an inexpensive bus for connecting many
-types of devices with infrequent or low bandwidth communications needs.
-I2C is widely used with embedded systems.  Some systems use variants that
-don't meet branding requirements, and so are not advertised as being I2C.
+I²C (pronounce: I squared C and written I2C in the kernel documentation) is
+a protocol developed by Philips. It is a slow two-wire protocol (variable
+speed, up to 400 kHz), with a high speed extension (3.4 MHz).  It provides
+an inexpensive bus for connecting many types of devices with infrequent or
+low bandwidth communications needs.  I2C is widely used with embedded
+systems.  Some systems use variants that don't meet branding requirements,
+and so are not advertised as being I2C but with different names, e.g. TWI
+(Two Wire Interface), IIC.
+
+The official I2C specification is the `"I2C-bus specification and user
+manual" (UM10204) <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_
+published by NXP Semiconductors.
 
 SMBus (System Management Bus) is based on the I2C protocol, and is mostly
 a subset of I2C protocols and signaling.  Many I2C devices will work on an
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 03/26] docs: i2c: summary: rewrite the "terminology" section
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
  2020-01-05 22:49   ` [PATCH 02/26] docs: i2c: summary: extend introduction Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-20 10:04     ` Jean Delvare
  2020-01-05 22:49   ` [PATCH 04/26] docs: i2c: call it "I2C" consistently Luca Ceresoli
                     ` (20 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

This section, partly dating back to the pre-git era, is somewhat
unclear and partly incorrect. Rewrite it almost completely including a
reference figure, concise but precise definition of each term and the
paths where drivers are found. Particular care has been put in clarifying
the relation between adapter and algorithm, which has no correspondence
in the I2C spec terminology.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/i2c.svg     | 1341 +++++++++++++++++++++++++++++++++
 Documentation/i2c/summary.rst |   35 +-
 2 files changed, 1362 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/i2c/i2c.svg

diff --git a/Documentation/i2c/i2c.svg b/Documentation/i2c/i2c.svg
new file mode 100644
index 000000000000..5979405ad1c3
--- /dev/null
+++ b/Documentation/i2c/i2c.svg
@@ -0,0 +1,1341 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   sodipodi:docname="i2c.svg"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   version="1.1"
+   id="svg2"
+   viewBox="0 0 813.34215 261.01596"
+   height="73.664505mm"
+   width="229.54323mm">
+  <defs
+     id="defs4">
+    <marker
+       inkscape:stockid="DotM"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker8861"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path8859"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)" />
+    </marker>
+    <marker
+       inkscape:isstock="true"
+       style="overflow:visible"
+       id="marker6165"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="DotM"
+       inkscape:collect="always">
+      <path
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         id="path6163"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:isstock="true"
+       style="overflow:visible"
+       id="marker2713"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="DotM">
+      <path
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         id="path2711"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="DotM"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="DotM"
+       style="overflow:visible"
+       inkscape:isstock="true"
+       inkscape:collect="always">
+      <path
+         id="path1795"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:isstock="true"
+       style="overflow:visible"
+       id="marker6389"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="Arrow2Mend">
+      <path
+         transform="scale(-0.6)"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         id="path6387"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleOutM"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleOutM"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4107"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="scale(0.4)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker5333"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path5335"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="scale(0.8)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleOutL"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path5049"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="scale(0.8)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="DotS"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="DotS"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path9326"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         style="fill:#404040;fill-opacity:1;fill-rule:evenodd;stroke:#404040;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.2,0,0,0.2,1.48,0.2)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mstart"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mstart"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path9283"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(0.6)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path9097"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker8935"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path8937"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker8781"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path8783"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Lend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Lend"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4700"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="EmptyTriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="EmptyTriangleOutL"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4502"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.8,0,0,0.8,-4.8,0)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <marker
+       inkscape:stockid="EmptyTriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="EmptyTriangleOutL-4"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4502-7"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.8,0,0,0.8,-4.8,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="EmptyTriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="EmptyTriangleOutL-4-4"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4502-7-5"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.8,0,0,0.8,-4.8,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="EmptyTriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="EmptyTriangleOutL-7"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4502-5"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.8,0,0,0.8,-4.8,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="EmptyTriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="EmptyTriangleOutL-6"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4502-2"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.8,0,0,0.8,-4.8,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="EmptyTriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="EmptyTriangleOutL-78"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4502-57"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.8,0,0,0.8,-4.8,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="EmptyTriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="EmptyTriangleOutL-1"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4502-8"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.8,0,0,0.8,-4.8,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="EmptyTriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="EmptyTriangleOutL-9"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4502-75"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.8,0,0,0.8,-4.8,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="EmptyTriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="EmptyTriangleOutL-78-2"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4502-57-6"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.8,0,0,0.8,-4.8,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend-3"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4369-6"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend-3-5"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4369-6-3"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend-3-5-6"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4369-6-3-2"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend-3-5-6-1"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4369-6-3-2-2"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend-3-5-7"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4369-6-3-0"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend-3-9"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4369-6-36"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend-31"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4369-9"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend-3-5-7-5"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4369-6-3-0-4"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend-3-9-6"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4369-6-36-5"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend-3-5-7-3"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4369-6-3-0-5"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-3"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-1"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-3-7"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-1-8"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-6"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-1"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-6-6"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-1-3"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-2"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-0"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-6-5"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-1-5"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-4"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-7"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-6-5-9"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-1-5-3"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-6-5-4"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-1-5-5"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-6-5-4-4"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-1-5-5-3"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-6-5-4-4-9"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-1-5-5-3-2"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-6-5-4-4-6"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-1-5-5-3-8"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-6-5-4-4-2"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-1-5-5-3-7"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-3"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-6"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-6-5-4-4-6-5"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-1-5-5-3-8-3"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-27"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-09"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-27-6"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-09-2"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-27-0"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-09-23"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-9"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-7"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-4-6"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-7-7"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-4-6-3"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-7-7-5"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-4-6-2"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-7-7-9"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleOutM"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleOutM-2"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path4107-7"
+         d="M 5.77,0 -2.88,5 V -5 Z"
+         style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="scale(0.4)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mstart"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mstart-9"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9283-3"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker9095-1-5-4-6-6"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path9097-2-0-7-7-0"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="DotM"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="DotM-3"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         inkscape:connector-curvature="0"
+         id="path1795-7"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)" />
+    </marker>
+    <marker
+       inkscape:isstock="true"
+       style="overflow:visible"
+       id="marker2713-9"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="DotM">
+      <path
+         inkscape:connector-curvature="0"
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         id="path2711-2" />
+    </marker>
+    <marker
+       inkscape:stockid="DotM"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="DotM-2"
+       style="overflow:visible"
+       inkscape:isstock="true"
+       inkscape:collect="always">
+      <path
+         inkscape:connector-curvature="0"
+         id="path1795-8"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)" />
+    </marker>
+    <marker
+       inkscape:isstock="true"
+       style="overflow:visible"
+       id="marker2713-3"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="DotM">
+      <path
+         inkscape:connector-curvature="0"
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         id="path2711-6" />
+    </marker>
+    <marker
+       inkscape:stockid="DotM"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="DotM-1"
+       style="overflow:visible"
+       inkscape:isstock="true"
+       inkscape:collect="always">
+      <path
+         inkscape:connector-curvature="0"
+         id="path1795-2"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)" />
+    </marker>
+    <marker
+       inkscape:isstock="true"
+       style="overflow:visible"
+       id="marker2713-94"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="DotM">
+      <path
+         inkscape:connector-curvature="0"
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         id="path2711-7" />
+    </marker>
+    <marker
+       inkscape:stockid="DotM"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="DotM-8"
+       style="overflow:visible"
+       inkscape:isstock="true"
+       inkscape:collect="always">
+      <path
+         inkscape:connector-curvature="0"
+         id="path1795-4"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)" />
+    </marker>
+    <marker
+       inkscape:isstock="true"
+       style="overflow:visible"
+       id="marker2713-36"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="DotM">
+      <path
+         inkscape:connector-curvature="0"
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         id="path2711-1" />
+    </marker>
+    <marker
+       inkscape:isstock="true"
+       style="overflow:visible"
+       id="marker6165-5"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="DotM">
+      <path
+         transform="matrix(0.4,0,0,0.4,2.96,0.4)"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+         d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+         id="path6163-5"
+         inkscape:connector-curvature="0" />
+    </marker>
+  </defs>
+  <sodipodi:namedview
+     showguides="true"
+     inkscape:window-maximized="1"
+     inkscape:window-y="0"
+     inkscape:window-x="0"
+     inkscape:window-height="1015"
+     inkscape:window-width="1920"
+     showgrid="true"
+     inkscape:current-layer="layer1"
+     inkscape:document-units="px"
+     inkscape:cy="214.66765"
+     inkscape:cx="-167.56857"
+     inkscape:zoom="0.70710678"
+     inkscape:pageshadow="2"
+     inkscape:pageopacity="0.0"
+     borderopacity="1.0"
+     bordercolor="#666666"
+     pagecolor="#ffffff"
+     id="base"
+     inkscape:snap-to-guides="true"
+     inkscape:snap-grids="true"
+     inkscape:snap-bbox="false"
+     inkscape:object-nodes="true"
+     fit-margin-top="5"
+     fit-margin-left="5"
+     fit-margin-right="5"
+     fit-margin-bottom="5">
+    <inkscape:grid
+       type="xygrid"
+       id="grid4451"
+       originx="-93.377219"
+       originy="-347.2523" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+        <dc:creator>
+          <cc:Agent>
+            <dc:title>Luca Ceresoli</dc:title>
+          </cc:Agent>
+        </dc:creator>
+        <dc:date>2020</dc:date>
+        <cc:license
+           rdf:resource="http://creativecommons.org/licenses/by-sa/4.0/" />
+      </cc:Work>
+      <cc:License
+         rdf:about="http://creativecommons.org/licenses/by-sa/4.0/">
+        <cc:permits
+           rdf:resource="http://creativecommons.org/ns#Reproduction" />
+        <cc:permits
+           rdf:resource="http://creativecommons.org/ns#Distribution" />
+        <cc:requires
+           rdf:resource="http://creativecommons.org/ns#Notice" />
+        <cc:requires
+           rdf:resource="http://creativecommons.org/ns#Attribution" />
+        <cc:permits
+           rdf:resource="http://creativecommons.org/ns#DerivativeWorks" />
+        <cc:requires
+           rdf:resource="http://creativecommons.org/ns#ShareAlike" />
+      </cc:License>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Livello 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-93.377215,-444.09395)">
+    <rect
+       style="opacity:1;fill:#ffb9b9;fill-opacity:1;stroke:#f00000;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect4424-3-2-9-7"
+       width="112.5"
+       height="113.75008"
+       x="112.5"
+       y="471.11221"
+       rx="0"
+       ry="0" />
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="167.5354"
+       y="521.46259"
+       id="text4349"><tspan
+         sodipodi:role="line"
+         x="167.5354"
+         y="521.46259"
+         style="font-size:25px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle"
+         id="tspan1273">I2C</tspan><tspan
+         sodipodi:role="line"
+         x="167.5354"
+         y="552.71259"
+         style="font-size:25px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle"
+         id="tspan1285">Master</tspan></text>
+    <rect
+       style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate"
+       id="rect4424-3-2-9-7-3-3-5-3"
+       width="112.49998"
+       height="112.50001"
+       x="262.5"
+       y="471.11218"
+       rx="0"
+       ry="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968767;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 112.50002,639.86223 c 712.50002,0 712.50002,0 712.50002,0"
+       id="path4655-9-3-65-5-6"
+       inkscape:connector-curvature="0" />
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="318.59131"
+       y="520.83752"
+       id="text4349-26"><tspan
+         sodipodi:role="line"
+         x="318.59131"
+         y="520.83752"
+         style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
+         id="tspan1273-8">I2C</tspan><tspan
+         sodipodi:role="line"
+         x="318.59131"
+         y="552.08752"
+         style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
+         id="tspan1287">Slave</tspan></text>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968767;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 112.49995,677.36223 c 712.50005,0 712.50005,0 712.50005,0"
+       id="path4655-9-3-65-5-6-2"
+       inkscape:connector-curvature="0" />
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="861.07312"
+       y="687.03937"
+       id="text4349-7"><tspan
+         sodipodi:role="line"
+         x="861.07312"
+         y="687.03937"
+         style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;writing-mode:lr-tb;direction:ltr;text-anchor:middle;stroke-width:1px"
+         id="tspan1285-9">SCL</tspan></text>
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot1627"
+       style="font-style:normal;font-weight:normal;font-size:40px;line-height:125%;font-family:Sans;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><flowRegion
+         id="flowRegion1629"><rect
+           id="rect1631"
+           width="220"
+           height="120"
+           x="140"
+           y="-126.29921" /></flowRegion><flowPara
+         id="flowPara1633" /></flowRoot>    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="863.31921"
+       y="648.96735"
+       id="text4349-7-3"><tspan
+         sodipodi:role="line"
+         x="863.31921"
+         y="648.96735"
+         style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
+         id="tspan1285-9-6">SDA</tspan></text>
+    <rect
+       style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate"
+       id="rect4424-3-2-9-7-3-3-5-3-0"
+       width="112.49998"
+       height="112.50002"
+       x="412.5"
+       y="471.11215"
+       rx="0"
+       ry="0" />
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="468.59131"
+       y="520.83746"
+       id="text4349-26-6"><tspan
+         sodipodi:role="line"
+         x="468.59131"
+         y="520.83746"
+         style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
+         id="tspan1273-8-2">I2C</tspan><tspan
+         sodipodi:role="line"
+         x="468.59131"
+         y="552.08746"
+         style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
+         id="tspan1287-6">Slave</tspan></text>
+    <rect
+       style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate"
+       id="rect4424-3-2-9-7-3-3-5-3-1"
+       width="112.49998"
+       height="112.50002"
+       x="562.5"
+       y="471.11215"
+       rx="0"
+       ry="0" />
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="618.59131"
+       y="520.83746"
+       id="text4349-26-8"><tspan
+         sodipodi:role="line"
+         x="618.59131"
+         y="520.83746"
+         style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
+         id="tspan1273-8-7">I2C</tspan><tspan
+         sodipodi:role="line"
+         x="618.59131"
+         y="552.08746"
+         style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
+         id="tspan1287-9">Slave</tspan></text>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM)"
+       d="m 150,583.61221 v 93.75"
+       id="path4655-9-3-65-5-6-20"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713)"
+       d="m 187.5,583.61221 v 56.25"
+       id="path4655-9-3-65-5-6-20-2"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM-2)"
+       d="m 300,583.61221 v 93.75"
+       id="path4655-9-3-65-5-6-20-9"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713-9)"
+       d="m 337.5,583.61221 v 56.25"
+       id="path4655-9-3-65-5-6-20-2-7"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM-1)"
+       d="m 450,583.61221 v 93.75"
+       id="path4655-9-3-65-5-6-20-93"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713-3)"
+       d="m 487.5,583.61221 v 56.25"
+       id="path4655-9-3-65-5-6-20-2-1"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM-8)"
+       d="m 600,583.61221 v 93.75"
+       id="path4655-9-3-65-5-6-20-5"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713-94)"
+       d="m 637.5,583.61221 v 56.25"
+       id="path4655-9-3-65-5-6-20-2-0"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:url(#marker6165);marker-end:url(#marker6165)"
+       d="m 750,471.11221 v 28.125 l 9.375,9.375 -18.74999,18.75 18.74999,18.75 -18.74999,18.75 18.74999,18.75 -9.375,9.375 v 28.125 0 0 56.25"
+       id="path6135"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cccccccccccc" />
+    <path
+       style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:url(#marker8861);marker-end:url(#marker6165-5)"
+       d="m 787.49999,471.11221 v 28.125 l 9.375,9.375 -18.74999,18.75 18.74999,18.75 -18.74999,18.75 18.74999,18.75 -9.375,9.375 v 28.125 0 0 18.75001"
+       id="path6135-4"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cccccccccccc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968719;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 712.5,471.11221 c 112.49999,0 112.49999,0 112.49999,0"
+       id="path4655-9-3-65-5-6-7"
+       inkscape:connector-curvature="0" />
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="859.94275"
+       y="480.03558"
+       id="text4349-7-3-6"><tspan
+         sodipodi:role="line"
+         x="859.94275"
+         y="480.03558"
+         style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
+         id="tspan1285-9-6-5">V<tspan
+   style="font-size:64.99999762%;baseline-shift:sub"
+   id="tspan9307">DD</tspan></tspan></text>
+  </g>
+</svg>
diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
index b7d3e620155b..fc69d9567d9d 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -31,21 +31,28 @@ implement all the common SMBus protocol semantics or messages.
 Terminology
 ===========
 
-When we talk about I2C, we use the following terms::
+Using the terminology from the official documentation, the I2C bus connects
+one or more *master* chips and one or more *slave* chips.
 
-  Bus    -> Algorithm
-            Adapter
-  Device -> Driver
-            Client
+.. kernel-figure::  i2c.svg
+   :alt:    Simple I2C bus with one master and 3 slaves
 
-An Algorithm driver contains general code that can be used for a whole class
-of I2C adapters. Each specific adapter driver either depends on one algorithm
-driver, or includes its own implementation.
+   Simple I2C bus
 
-A Driver driver (yes, this sounds ridiculous, sorry) contains the general
-code to access some type of device. Each detected device gets its own
-data in the Client structure. Usually, Driver and Client are more closely
-integrated than Algorithm and Adapter.
+A **master** chip is a node that starts communications with slaves. In the
+Linux kernel implementation it is called an **adapter** or bus. Adapter
+drivers are in the ``drivers/i2c/busses/`` subdirectory.
 
-For a given configuration, you will need a driver for your I2C bus, and
-drivers for your I2C devices (usually one driver for each device).
+An **algorithm** contains general code that can be used to implement a
+whole class of I2C adapters. Each specific adapter driver either depends on
+one algorithm driver, or includes its own implementation.
+
+A **slave** chip is a node that responds to communications when addressed
+by the master. In Linux it is called a **client**. Client drivers are kept
+in a directory specific to the feature they provide, for example
+``drivers/media/gpio/`` for GPIO expanders and ``drivers/media/i2c/`` for
+video-related chips.
+
+For the example configuration in figure, you will need a driver for your
+I2C adapter, and drivers for your I2C devices (usually one driver for each
+device).
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 04/26] docs: i2c: call it "I2C" consistently
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
  2020-01-05 22:49   ` [PATCH 02/26] docs: i2c: summary: extend introduction Luca Ceresoli
  2020-01-05 22:49   ` [PATCH 03/26] docs: i2c: summary: rewrite the "terminology" section Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-07 10:33     ` Peter Rosin
  2020-01-16  9:39     ` Jean Delvare
  2020-01-05 22:49   ` [PATCH 05/26] docs: i2c: fix typo Luca Ceresoli
                     ` (19 subsequent siblings)
  22 siblings, 2 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Uppercase "I2C" is used almost everywhere in the docs, but the lowercase
version "i2c" is used somewhere. Use the uppercase form consistently.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/dev-interface.rst         | 18 +++---
 Documentation/i2c/dma-considerations.rst    |  2 +-
 Documentation/i2c/i2c-protocol.rst          |  4 +-
 Documentation/i2c/i2c-topology.rst          | 66 ++++++++++-----------
 Documentation/i2c/instantiating-devices.rst |  2 +-
 Documentation/i2c/old-module-parameters.rst |  6 +-
 Documentation/i2c/slave-interface.rst       |  4 +-
 Documentation/i2c/writing-clients.rst       |  4 +-
 8 files changed, 53 insertions(+), 53 deletions(-)

diff --git a/Documentation/i2c/dev-interface.rst b/Documentation/i2c/dev-interface.rst
index 69c23a3c2b1b..c3717a87df12 100644
--- a/Documentation/i2c/dev-interface.rst
+++ b/Documentation/i2c/dev-interface.rst
@@ -2,26 +2,26 @@
 I2C Device Interface
 ====================
 
-Usually, i2c devices are controlled by a kernel driver. But it is also
+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.
 
-Each registered i2c adapter gets a number, counting from 0. You can
+Each registered I2C adapter gets a number, counting from 0. You can
 examine /sys/class/i2c-dev/ to see what number corresponds to which adapter.
 Alternatively, you can run "i2cdetect -l" to obtain a formatted list of all
-i2c adapters present on your system at a given time. i2cdetect is part of
+I2C adapters present on your system at a given time. i2cdetect is part of
 the i2c-tools package.
 
 I2C device files are character device files with major device number 89
 and a minor device number corresponding to the number assigned as
 explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ...,
-i2c-10, ...). All 256 minor device numbers are reserved for i2c.
+i2c-10, ...). All 256 minor device numbers are reserved for I2C.
 
 
 C example
 =========
 
-So let's say you want to access an i2c adapter from a C program.
+So let's say you want to access an I2C adapter from a C program.
 First, you need to include these two headers::
 
   #include <linux/i2c-dev.h>
@@ -66,7 +66,7 @@ the device supports them. Both are illustrated below::
   /* Using SMBus commands */
   res = i2c_smbus_read_word_data(file, reg);
   if (res < 0) {
-    /* ERROR HANDLING: i2c transaction failed */
+    /* ERROR HANDLING: I2C transaction failed */
   } else {
     /* res contains the read word */
   }
@@ -79,12 +79,12 @@ the device supports them. Both are illustrated below::
   buf[1] = 0x43;
   buf[2] = 0x65;
   if (write(file, buf, 3) != 3) {
-    /* ERROR HANDLING: i2c transaction failed */
+    /* ERROR HANDLING: I2C transaction failed */
   }
 
   /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */
   if (read(file, buf, 1) != 1) {
-    /* ERROR HANDLING: i2c transaction failed */
+    /* ERROR HANDLING: I2C transaction failed */
   } else {
     /* buf[0] contains the read byte */
   }
@@ -144,7 +144,7 @@ The following IOCTLs are defined:
   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.
+You can do plain I2C transactions by using read(2) and write(2) calls.
 You do not need to pass the address byte; instead, set it through
 ioctl I2C_SLAVE before you try to access the device.
 
diff --git a/Documentation/i2c/dma-considerations.rst b/Documentation/i2c/dma-considerations.rst
index 203002054120..142d52ce9ebb 100644
--- a/Documentation/i2c/dma-considerations.rst
+++ b/Documentation/i2c/dma-considerations.rst
@@ -2,7 +2,7 @@
 Linux I2C and DMA
 =================
 
-Given that i2c is a low-speed bus, over which the majority of messages
+Given that I2C is a low-speed bus, over which the majority of messages
 transferred are small, it is not considered a prime user of DMA access. At this
 time of writing, only 10% of I2C bus master drivers have DMA support
 implemented. And the vast majority of transactions are so small that setting up
diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst
index 2f8fcf671b2e..0222c97f3436 100644
--- a/Documentation/i2c/i2c-protocol.rst
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -2,7 +2,7 @@
 I2C Protocol
 ============
 
-This document describes the i2c protocol. Or will, when it is finished :-)
+This document describes the I2C protocol. Or will, when it is finished :-)
 
 Key to symbols
 ==============
@@ -57,7 +57,7 @@ Modified transactions
 =====================
 
 The following modifications to the I2C protocol can also be generated by
-setting these flags for i2c messages. With the exception of I2C_M_NOSTART, they
+setting these flags for I2C messages. With the exception of I2C_M_NOSTART, they
 are usually only needed to work around device issues:
 
 I2C_M_IGNORE_NAK:
diff --git a/Documentation/i2c/i2c-topology.rst b/Documentation/i2c/i2c-topology.rst
index 0c1ae95f6a97..0875090d6aeb 100644
--- a/Documentation/i2c/i2c-topology.rst
+++ b/Documentation/i2c/i2c-topology.rst
@@ -2,8 +2,8 @@
 I2C topology
 ============
 
-There are a couple of reasons for building more complex i2c topologies
-than a straight-forward i2c bus with one adapter and one or more devices.
+There are a couple of reasons for building more complex I2C topologies
+than a straight-forward I2C bus with one adapter and one or more devices.
 
 1. A mux may be needed on the bus to prevent address collisions.
 
@@ -11,20 +11,20 @@ than a straight-forward i2c bus with one adapter and one or more devices.
    may be needed to determine if it is ok to access the bus.
 
 3. A device (particularly RF tuners) may want to avoid the digital noise
-   from the i2c bus, at least most of the time, and sits behind a gate
+   from the I2C bus, at least most of the time, and sits behind a gate
    that has to be operated before the device can be accessed.
 
 Etc
 ===
 
-These constructs are represented as i2c adapter trees by Linux, where
+These constructs are represented as I2C adapter trees by Linux, where
 each adapter has a parent adapter (except the root adapter) and zero or
 more child adapters. The root adapter is the actual adapter that issues
-i2c transfers, and all adapters with a parent are part of an "i2c-mux"
+I2C transfers, and all adapters with a parent are part of an "i2c-mux"
 object (quoted, since it can also be an arbitrator or a gate).
 
 Depending of the particular mux driver, something happens when there is
-an i2c transfer on one of its child adapters. The mux driver can
+an I2C transfer on one of its child adapters. The mux driver can
 obviously operate a mux, but it can also do arbitration with an external
 bus master or open a gate. The mux driver has two operations for this,
 select and deselect. select is called before the transfer and (the
@@ -34,7 +34,7 @@ optional) deselect is called after the transfer.
 Locking
 =======
 
-There are two variants of locking available to i2c muxes, they can be
+There are two variants of locking available to I2C muxes, they can be
 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:
@@ -45,7 +45,7 @@ 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
-                          same i2c root adapter that they mux.
+                          same I2C root adapter that they mux.
 i2c-mux-gpmux             Normally parent-locked, mux-locked iff
                           specified in device-tree.
 i2c-mux-ltc4306           Mux-locked
@@ -54,7 +54,7 @@ i2c-mux-pca9541           Parent-locked
 i2c-mux-pca954x           Parent-locked
 i2c-mux-pinctrl           Normally parent-locked, mux-locked iff
                           all involved pinctrl devices are controlled
-                          by the same i2c root adapter that they mux.
+                          by the same I2C root adapter that they mux.
 i2c-mux-reg               Parent-locked
 ======================    =============================================
 
@@ -83,9 +83,9 @@ Mux-locked muxes
 Mux-locked muxes does not lock the entire parent adapter during the
 full select-transfer-deselect transaction, only the muxes on the parent
 adapter are locked. Mux-locked muxes are mostly interesting if the
-select and/or deselect operations must use i2c transfers to complete
+select and/or deselect operations must use I2C transfers to complete
 their tasks. Since the parent adapter is not fully locked during the
-full transaction, unrelated i2c transfers may interleave the different
+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.
 
@@ -109,14 +109,14 @@ ML2. It is not safe to build arbitrary topologies with two (or more)
 
 ML3. A mux-locked mux cannot be used by a driver for auto-closing
      gates/muxes, i.e. something that closes automatically after a given
-     number (one, in most cases) of i2c transfers. Unrelated i2c transfers
+     number (one, in most cases) of I2C transfers. Unrelated I2C transfers
      may creep in and close prematurely.
 
-ML4. If any non-i2c operation in the mux driver changes the i2c mux state,
+ML4. If any non-I2C operation in the mux driver changes the I2C mux state,
      the driver has to lock the root adapter during that operation.
      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.
+     behind the mux, when an unrelated I2C transfer is in flight during
+     the non-I2C mux-changing operation.
 ==== =====================================================================
 
 
@@ -137,14 +137,14 @@ Mux-locked Example
 
 When there is an access to D1, this happens:
 
- 1. Someone issues an i2c-transfer to D1.
+ 1. Someone issues an I2C-transfer to D1.
  2. M1 locks muxes on its parent (the root adapter in this case).
  3. M1 calls ->select to ready the mux.
- 4. M1 (presumably) does some i2c-transfers as part of its select.
-    These transfers are normal i2c-transfers that locks the parent
+ 4. M1 (presumably) does some I2C-transfers as part of its select.
+    These transfers are normal I2C-transfers that locks the parent
     adapter.
- 5. M1 feeds the i2c-transfer from step 1 to its parent adapter as a
-    normal i2c-transfer that locks the parent adapter.
+ 5. M1 feeds the I2C-transfer from step 1 to its parent adapter as a
+    normal I2C-transfer that locks the parent adapter.
  6. M1 calls ->deselect, if it has one.
  7. Same rules as in step 4, but for ->deselect.
  8. M1 unlocks muxes on its parent.
@@ -159,8 +159,8 @@ Parent-locked muxes
 
 Parent-locked muxes lock the parent adapter during the full select-
 transfer-deselect transaction. The implication is that the mux driver
-has to ensure that any and all i2c transfers through that parent
-adapter during the transaction are unlocked i2c transfers (using e.g.
+has to ensure that any and all I2C transfers through that parent
+adapter during the transaction are unlocked I2C transfers (using e.g.
 __i2c_transfer), or a deadlock will follow. There are a couple of
 caveats.
 
@@ -169,12 +169,12 @@ 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
      and the actual transfer (e.g. if the child mux is auto-closing
-     and the parent mux issus i2c-transfers as part of its select).
+     and the parent mux issus I2C-transfers as part of its select).
      This is especially the case if the parent mux is mux-locked, but
      it may also happen if the parent mux is parent-locked.
 
 PL2. If select/deselect calls out to other subsystems such as gpio,
-     pinctrl, regmap or iio, it is essential that any i2c transfers
+     pinctrl, regmap or iio, it is essential that any I2C transfers
      caused by these subsystems are unlocked. This can be convoluted to
      accomplish, maybe even impossible if an acceptably clean solution
      is sought.
@@ -197,15 +197,15 @@ Parent-locked Example
 
 When there is an access to D1, this happens:
 
- 1.  Someone issues an i2c-transfer to D1.
+ 1.  Someone issues an I2C-transfer to D1.
  2.  M1 locks muxes on its parent (the root adapter in this case).
  3.  M1 locks its parent adapter.
  4.  M1 calls ->select to ready the mux.
- 5.  If M1 does any i2c-transfers (on this root adapter) as part of
-     its select, those transfers must be unlocked i2c-transfers so
+ 5.  If M1 does any I2C-transfers (on this root adapter) as part of
+     its select, those transfers must be unlocked I2C-transfers so
      that they do not deadlock the root adapter.
- 6.  M1 feeds the i2c-transfer from step 1 to the root adapter as an
-     unlocked i2c-transfer, so that it does not deadlock the parent
+ 6.  M1 feeds the I2C-transfer from step 1 to the root adapter as an
+     unlocked I2C-transfer, so that it does not deadlock the parent
      adapter.
  7.  M1 calls ->deselect, if it has one.
  8.  Same rules as in step 5, but for ->deselect.
@@ -240,7 +240,7 @@ and specifically when M2 requests its parent to lock, M1 passes
 the buck to the root adapter).
 
 This topology is bad if M2 is an auto-closing mux and M1->select
-issues any unlocked i2c transfers on the root adapter that may leak
+issues any unlocked I2C transfers on the root adapter that may leak
 through and be seen by the M2 adapter, thus closing M2 prematurely.
 
 
@@ -286,14 +286,14 @@ point.
 
 This kind of topology is generally not suitable and should probably
 be avoided. The reason is that M2 probably assumes that there will
-be no i2c transfers during its calls to ->select and ->deselect, and
+be no I2C transfers during its calls to ->select and ->deselect, and
 if there are, any such transfers might appear on the slave side of M2
-as partial i2c transfers, i.e. garbage or worse. This might cause
+as partial I2C transfers, i.e. garbage or worse. This might cause
 device lockups and/or other problems.
 
 The topology is especially troublesome if M2 is an auto-closing
 mux. In that case, any interleaved accesses to D4 might close M2
-prematurely, as might any i2c-transfers part of M1->select.
+prematurely, as might any I2C-transfers part of M1->select.
 
 But if M2 is not making the above stated assumption, and if M2 is not
 auto-closing, the topology is fine.
diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
index 875ebe9e78e3..cf5d9828e823 100644
--- a/Documentation/i2c/instantiating-devices.rst
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -188,7 +188,7 @@ destroyed automatically when the driver which detected them is removed,
 or when the underlying I2C bus is itself destroyed, whichever happens
 first.
 
-Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6
+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:
 
diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
index a1939512ad66..78a6950e5763 100644
--- a/Documentation/i2c/old-module-parameters.rst
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -2,14 +2,14 @@
 I2C device driver binding control from user-space
 =================================================
 
-Up to kernel 2.6.32, many i2c drivers used helper macros provided by
+Up to kernel 2.6.32, many I2C drivers used helper macros provided by
 <linux/i2c.h> which created standard module parameters to let the user
-control how the driver would probe i2c buses and attach to devices. These
+control how the driver would probe I2C buses and attach to devices. These
 parameters were known as "probe" (to let the driver probe for an extra
 address), "force" (to forcibly attach the driver to a given device) and
 "ignore" (to prevent a driver from probing a given address).
 
-With the conversion of the i2c subsystem to the standard device driver
+With the conversion of the I2C subsystem to the standard device driver
 binding model, it became clear that these per-module parameters were no
 longer needed, and that a centralized implementation was possible. The new,
 sysfs-based interface is described in the documentation file
diff --git a/Documentation/i2c/slave-interface.rst b/Documentation/i2c/slave-interface.rst
index c769bd6a15bf..82ea3e1d6fe4 100644
--- a/Documentation/i2c/slave-interface.rst
+++ b/Documentation/i2c/slave-interface.rst
@@ -59,7 +59,7 @@ The bus driver sends an event to the backend using the following function::
 
 	ret = i2c_slave_event(client, event, &val)
 
-'client' describes the i2c slave device. 'event' is one of the special event
+'client' describes the I2C slave device. 'event' is one of the special event
 types described hereafter. 'val' holds an u8 value for the data byte to be
 read/written and is thus bidirectional. The pointer to val must always be
 provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
@@ -143,7 +143,7 @@ Bus driver support
 If you want to add slave support to the bus driver:
 
 * implement calls to register/unregister the slave and add those to the
-  struct i2c_algorithm. When registering, you probably need to set the i2c
+  struct i2c_algorithm. When registering, you probably need to set the I2C
   slave address and enable slave specific interrupts. If you use runtime pm, you
   should use pm_runtime_get_sync() because your device usually needs to be
   powered on always to be able to detect its slave address. When unregistering,
diff --git a/Documentation/i2c/writing-clients.rst b/Documentation/i2c/writing-clients.rst
index ced309b5e0cc..1bf4b973c673 100644
--- a/Documentation/i2c/writing-clients.rst
+++ b/Documentation/i2c/writing-clients.rst
@@ -95,7 +95,7 @@ to gather information from the client, or write new information to the
 client.
 
 I have found it useful to define foo_read and foo_write functions for this.
-For some cases, it will be easier to call the i2c functions directly,
+For some cases, it will be easier to call the I2C functions directly,
 but many chips have some kind of register-value idea that can easily
 be encapsulated.
 
@@ -344,7 +344,7 @@ Plain I2C communication
 	int i2c_master_recv(struct i2c_client *client, char *buf, int count);
 
 These routines read and write some bytes from/to a client. The client
-contains the i2c address, so you do not have to include it. The second
+contains the I2C address, so you do not have to include it. The second
 parameter contains the bytes to read/write, the third the number of bytes
 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
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 05/26] docs: i2c: fix typo
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (2 preceding siblings ...)
  2020-01-05 22:49   ` [PATCH 04/26] docs: i2c: call it "I2C" consistently Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-07 10:33     ` Peter Rosin
  2020-01-16  9:40     ` Jean Delvare
  2020-01-05 22:49   ` [PATCH 06/26] docs: i2c: replace "I2C-transfer" -> "I2C transfer" consistently Luca Ceresoli
                     ` (18 subsequent siblings)
  22 siblings, 2 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Fix "issus" -> "issues".

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/i2c-topology.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/i2c/i2c-topology.rst b/Documentation/i2c/i2c-topology.rst
index 0875090d6aeb..b413ef6a6773 100644
--- a/Documentation/i2c/i2c-topology.rst
+++ b/Documentation/i2c/i2c-topology.rst
@@ -169,7 +169,7 @@ 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
      and the actual transfer (e.g. if the child mux is auto-closing
-     and the parent mux issus I2C-transfers as part of its select).
+     and the parent mux issues I2C-transfers as part of its select).
      This is especially the case if the parent mux is mux-locked, but
      it may also happen if the parent mux is parent-locked.
 
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 06/26] docs: i2c: replace "I2C-transfer" -> "I2C transfer" consistently
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (3 preceding siblings ...)
  2020-01-05 22:49   ` [PATCH 05/26] docs: i2c: fix typo Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-07 10:34     ` Peter Rosin
  2020-01-20 10:07     ` Jean Delvare
  2020-01-05 22:49   ` [PATCH 07/26] docs: i2c: i2c-protocol: fix kernel-doc function syntax Luca Ceresoli
                     ` (17 subsequent siblings)
  22 siblings, 2 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

"I2C transfer" is a legitimate english sentence, no need for a hyphen
between the two words, as as such it is used in most of the
documentation. Remove the hyphen in the few places where it is present.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/i2c-topology.rst | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/Documentation/i2c/i2c-topology.rst b/Documentation/i2c/i2c-topology.rst
index b413ef6a6773..2a18b53e3508 100644
--- a/Documentation/i2c/i2c-topology.rst
+++ b/Documentation/i2c/i2c-topology.rst
@@ -137,14 +137,14 @@ Mux-locked Example
 
 When there is an access to D1, this happens:
 
- 1. Someone issues an I2C-transfer to D1.
+ 1. Someone issues an I2C transfer to D1.
  2. M1 locks muxes on its parent (the root adapter in this case).
  3. M1 calls ->select to ready the mux.
- 4. M1 (presumably) does some I2C-transfers as part of its select.
-    These transfers are normal I2C-transfers that locks the parent
+ 4. M1 (presumably) does some I2C transfers as part of its select.
+    These transfers are normal I2C transfers that locks the parent
     adapter.
- 5. M1 feeds the I2C-transfer from step 1 to its parent adapter as a
-    normal I2C-transfer that locks the parent adapter.
+ 5. M1 feeds the I2C transfer from step 1 to its parent adapter as a
+    normal I2C transfer that locks the parent adapter.
  6. M1 calls ->deselect, if it has one.
  7. Same rules as in step 4, but for ->deselect.
  8. M1 unlocks muxes on its parent.
@@ -169,7 +169,7 @@ 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
      and the actual transfer (e.g. if the child mux is auto-closing
-     and the parent mux issues I2C-transfers as part of its select).
+     and the parent mux issues I2C transfers as part of its select).
      This is especially the case if the parent mux is mux-locked, but
      it may also happen if the parent mux is parent-locked.
 
@@ -197,15 +197,15 @@ Parent-locked Example
 
 When there is an access to D1, this happens:
 
- 1.  Someone issues an I2C-transfer to D1.
+ 1.  Someone issues an I2C transfer to D1.
  2.  M1 locks muxes on its parent (the root adapter in this case).
  3.  M1 locks its parent adapter.
  4.  M1 calls ->select to ready the mux.
- 5.  If M1 does any I2C-transfers (on this root adapter) as part of
-     its select, those transfers must be unlocked I2C-transfers so
+ 5.  If M1 does any I2C transfers (on this root adapter) as part of
+     its select, those transfers must be unlocked I2C transfers so
      that they do not deadlock the root adapter.
- 6.  M1 feeds the I2C-transfer from step 1 to the root adapter as an
-     unlocked I2C-transfer, so that it does not deadlock the parent
+ 6.  M1 feeds the I2C transfer from step 1 to the root adapter as an
+     unlocked I2C transfer, so that it does not deadlock the parent
      adapter.
  7.  M1 calls ->deselect, if it has one.
  8.  Same rules as in step 5, but for ->deselect.
@@ -293,7 +293,7 @@ device lockups and/or other problems.
 
 The topology is especially troublesome if M2 is an auto-closing
 mux. In that case, any interleaved accesses to D4 might close M2
-prematurely, as might any I2C-transfers part of M1->select.
+prematurely, as might any I2C transfers part of M1->select.
 
 But if M2 is not making the above stated assumption, and if M2 is not
 auto-closing, the topology is fine.
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 07/26] docs: i2c: i2c-protocol: fix kernel-doc function syntax
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (4 preceding siblings ...)
  2020-01-05 22:49   ` [PATCH 06/26] docs: i2c: replace "I2C-transfer" -> "I2C transfer" consistently Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-20 10:51     ` Jean Delvare
  2020-01-05 22:49   ` [PATCH 08/26] docs: i2c: i2c-protocol: properly name start and stop conditions Luca Ceresoli
                     ` (16 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

This clarifies these are functions and adds a hyperlink to the function
documentation.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/i2c-protocol.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst
index 0222c97f3436..f289d7759a51 100644
--- a/Documentation/i2c/i2c-protocol.rst
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -28,7 +28,7 @@ Count (8 bits): A data byte containing the length of a block operation.
 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
 
@@ -36,7 +36,7 @@ This corresponds to i2c_master_send::
 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
 
@@ -44,7 +44,7 @@ This corresponds to i2c_master_recv::
 Combined transactions
 =====================
 
-This corresponds to i2c_transfer
+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
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 08/26] docs: i2c: i2c-protocol: properly name start and stop conditions
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (5 preceding siblings ...)
  2020-01-05 22:49   ` [PATCH 07/26] docs: i2c: i2c-protocol: fix kernel-doc function syntax Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-20 12:49     ` Jean Delvare
  2020-01-05 22:49   ` [PATCH 09/26] docs: i2c: i2c-protocol: remove unneeded colons from table Luca Ceresoli
                     ` (15 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

In I2C there is no such thing as a "start bit" or a "stop bit". Use the
proper naming: "start condition" and "stop condition".

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/i2c-protocol.rst | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst
index f289d7759a51..c090003f55ed 100644
--- a/Documentation/i2c/i2c-protocol.rst
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -8,8 +8,8 @@ Key to symbols
 ==============
 
 =============== =============================================================
-S     (1 bit) : Start bit
-P     (1 bit) : Stop bit
+S             : Start condition
+P             : Stop condition
 Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
 A, NA (1 bit) : Accept and reverse accept bit.
 Addr  (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
@@ -46,9 +46,9 @@ 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::
+They are just like the above transactions, but instead of a stop
+condition P a start condition S is sent and the transaction continues.
+An example of a byte read, followed by a byte write::
 
   S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
 
@@ -77,8 +77,9 @@ I2C_M_NOSTART:
       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.
+    we do not generate Addr, but we do generate the start condition S.
+    This will probably confuse all other clients on your bus, so don't
+    try this.
 
     This is often used to gather transmits from multiple data buffers in
     system memory into something that appears as a single transfer to the
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 09/26] docs: i2c: i2c-protocol: remove unneeded colons from table
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (6 preceding siblings ...)
  2020-01-05 22:49   ` [PATCH 08/26] docs: i2c: i2c-protocol: properly name start and stop conditions Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-20 13:38     ` Jean Delvare
  2020-01-05 22:49   ` [PATCH 10/26] docs: i2c: i2c-protocol: use proper names for ACK and NACK Luca Ceresoli
                     ` (14 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

These colons are not needed: the columns already nicely separate the
symbold from their description. They are also inconsistently preceded by
whitespace.

Remove the colons completely to simplify and clean up.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/i2c-protocol.rst | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst
index c090003f55ed..66adac3a5afd 100644
--- a/Documentation/i2c/i2c-protocol.rst
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -8,19 +8,19 @@ Key to symbols
 ==============
 
 =============== =============================================================
-S             : Start condition
-P             : Stop condition
-Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
-A, NA (1 bit) : Accept and reverse accept bit.
-Addr  (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
+S               Start condition
+P               Stop condition
+Rd/Wr (1 bit)   Read/Write bit. Rd equals 1, Wr equals 0.
+A, NA (1 bit)   Accept and reverse accept bit.
+Addr  (7 bits)  I2C 7 bit address. Note that this can be expanded as usual to
                 get a 10 bit I2C address.
-Comm  (8 bits): Command byte, a data byte which often selects a register on
+Comm  (8 bits)  Command byte, a data byte which often selects a register on
                 the device.
-Data  (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
+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.
+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
+[..]            Data sent by I2C device, as opposed to data sent by the
                 host adapter.
 =============== =============================================================
 
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 10/26] docs: i2c: i2c-protocol: use proper names for ACK and NACK
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (7 preceding siblings ...)
  2020-01-05 22:49   ` [PATCH 09/26] docs: i2c: i2c-protocol: remove unneeded colons from table Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-20 13:50     ` Jean Delvare
  2020-01-05 22:49   ` [PATCH 11/26] docs: i2c: smbus: fix link syntax Luca Ceresoli
                     ` (13 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Use the proper ACK and NACK naming from the I2C specification instead of
"accept" and "reverse accept".

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/i2c-protocol.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst
index 66adac3a5afd..9a4ac944cf9d 100644
--- a/Documentation/i2c/i2c-protocol.rst
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -11,7 +11,7 @@ Key to symbols
 S               Start condition
 P               Stop condition
 Rd/Wr (1 bit)   Read/Write bit. Rd equals 1, Wr equals 0.
-A, NA (1 bit)   Accept and reverse accept bit.
+A, NA (1 bit)   Acknowledge (ACK) and Not Acknowledge (NACK) bit
 Addr  (7 bits)  I2C 7 bit address. Note that this can be expanded as usual to
                 get a 10 bit I2C address.
 Comm  (8 bits)  Command byte, a data byte which often selects a register on
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 11/26] docs: i2c: smbus: fix link syntax
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (8 preceding siblings ...)
  2020-01-05 22:49   ` [PATCH 10/26] docs: i2c: i2c-protocol: use proper names for ACK and NACK Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-20 14:10     ` Jean Delvare
  2020-01-05 22:49   ` [PATCH 12/26] docs: i2c: smbus-protocol: properly name start and stop conditions Luca Ceresoli
                     ` (12 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Use the proper ReST syntax to generate a valid hyperlink.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/smbus-protocol.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index e30eb1d274c6..1600b09ec0be 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -27,8 +27,8 @@ a different protocol operation entirely.
 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.rst> for the details.
+adapter supports the transaction in question. See :doc:`functionality` for
+the details.
 
 
 Key to symbols
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 12/26] docs: i2c: smbus-protocol: properly name start and stop conditions
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (9 preceding siblings ...)
  2020-01-05 22:49   ` [PATCH 11/26] docs: i2c: smbus: fix link syntax Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-20 14:16     ` Jean Delvare
  2020-01-05 22:49   ` [PATCH 13/26] docs: i2c: smbus-protocol: remove unneeded colons from table Luca Ceresoli
                     ` (11 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

In I2C there is no such thing as a "start bit" or a "stop bit". Use the
proper naming: "start condition" and "stop condition".

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/smbus-protocol.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index 1600b09ec0be..8510eeda1dd0 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -35,8 +35,8 @@ Key to symbols
 ==============
 
 =============== =============================================================
-S     (1 bit) : Start bit
-P     (1 bit) : Stop bit
+S             : Start condition
+P             : Stop condition
 Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
 A, NA (1 bit) : Accept and reverse accept bit.
 Addr  (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 13/26] docs: i2c: smbus-protocol: remove unneeded colons from table
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (10 preceding siblings ...)
  2020-01-05 22:49   ` [PATCH 12/26] docs: i2c: smbus-protocol: properly name start and stop conditions Luca Ceresoli
@ 2020-01-05 22:49   ` Luca Ceresoli
  2020-01-20 14:23     ` Jean Delvare
  2020-01-05 22:50   ` [PATCH 14/26] docs: i2c: smbus-protocol: use proper names for ACK and NACK Luca Ceresoli
                     ` (10 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

These colons are not needed: the columns already nicely separate the
symbold from their description. They are also inconsistently preceded by
whitespace.

Remove the colons completely to simplify and clean up.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/smbus-protocol.rst | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index 8510eeda1dd0..fbadd4d25ad5 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -35,19 +35,19 @@ Key to symbols
 ==============
 
 =============== =============================================================
-S             : Start condition
-P             : Stop condition
-Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
-A, NA (1 bit) : Accept and reverse accept bit.
-Addr  (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
+S               Start condition
+P               Stop condition
+Rd/Wr (1 bit)   Read/Write bit. Rd equals 1, Wr equals 0.
+A, NA (1 bit)   Accept and reverse accept bit.
+Addr  (7 bits)  I2C 7 bit address. Note that this can be expanded as usual to
                 get a 10 bit I2C address.
-Comm  (8 bits): Command byte, a data byte which often selects a register on
+Comm  (8 bits)  Command byte, a data byte which often selects a register on
                 the device.
-Data  (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
+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.
+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
+[..]            Data sent by I2C device, as opposed to data sent by the host
                 adapter.
 =============== =============================================================
 
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 14/26] docs: i2c: smbus-protocol: use proper names for ACK and NACK
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (11 preceding siblings ...)
  2020-01-05 22:49   ` [PATCH 13/26] docs: i2c: smbus-protocol: remove unneeded colons from table Luca Ceresoli
@ 2020-01-05 22:50   ` Luca Ceresoli
  2020-01-20 14:26     ` Jean Delvare
  2020-01-05 22:50   ` [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax Luca Ceresoli
                     ` (9 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:50 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Use the proper ACK and NACK naming from the I2C specification instead of
"accept" and "reverse accept".

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/smbus-protocol.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index fbadd4d25ad5..10c4a989982c 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -38,7 +38,7 @@ Key to symbols
 S               Start condition
 P               Stop condition
 Rd/Wr (1 bit)   Read/Write bit. Rd equals 1, Wr equals 0.
-A, NA (1 bit)   Accept and reverse accept bit.
+A, NA (1 bit)   Acknowledge (ACK) and Not Acknowledge (NACK) bit
 Addr  (7 bits)  I2C 7 bit address. Note that this can be expanded as usual to
                 get a 10 bit I2C address.
 Comm  (8 bits)  Command byte, a data byte which often selects a register on
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (12 preceding siblings ...)
  2020-01-05 22:50   ` [PATCH 14/26] docs: i2c: smbus-protocol: use proper names for ACK and NACK Luca Ceresoli
@ 2020-01-05 22:50   ` Luca Ceresoli
  2020-01-20 14:44     ` Jean Delvare
  2020-01-05 22:50   ` [PATCH 16/26] docs: i2c: smbus-protocol: fix " Luca Ceresoli
                     ` (8 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:50 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Hyperlinks from function names are not generated in headings. Move them in
the plain text so they are rendered as clickable hyerlinks.

While there also remove an unneeded colon in a heading.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/smbus-protocol.rst | 64 ++++++++++++++++++----------
 1 file changed, 42 insertions(+), 22 deletions(-)

diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index 10c4a989982c..997945e90419 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -62,8 +62,10 @@ This sends a single bit to the device, at the place of the Rd/Wr bit::
 Functionality flag: I2C_FUNC_SMBUS_QUICK
 
 
-SMBus Receive Byte:  i2c_smbus_read_byte()
-==========================================
+SMBus Receive Byte
+==================
+
+Implemented by 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
@@ -75,8 +77,10 @@ the previous SMBus command::
 Functionality flag: I2C_FUNC_SMBUS_READ_BYTE
 
 
-SMBus Send Byte:  i2c_smbus_write_byte()
-========================================
+SMBus Send Byte
+===============
+
+Implemented by 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.
@@ -88,8 +92,10 @@ to a device.  See Receive Byte for more information.
 Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE
 
 
-SMBus Read Byte:  i2c_smbus_read_byte_data()
-============================================
+SMBus Read Byte
+===============
+
+Implemented by 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::
@@ -99,8 +105,10 @@ The register is specified through the Comm byte::
 Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA
 
 
-SMBus Read Word:  i2c_smbus_read_word_data()
-============================================
+SMBus Read Word
+===============
+
+Implemented by 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
@@ -115,8 +123,10 @@ available for reads where the two data bytes are the other way
 around (not SMBus compliant, but very popular.)
 
 
-SMBus Write Byte:  i2c_smbus_write_byte_data()
-==============================================
+SMBus Write Byte
+================
+
+Implemented by i2c_smbus_write_byte_data()
 
 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
@@ -129,8 +139,10 @@ the Read Byte operation.
 Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA
 
 
-SMBus Write Word:  i2c_smbus_write_word_data()
-==============================================
+SMBus Write Word
+================
+
+Implemented by 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
@@ -145,8 +157,8 @@ available for writes where the two data bytes are the other way
 around (not SMBus compliant, but very popular.)
 
 
-SMBus Process Call:
-===================
+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::
@@ -157,8 +169,10 @@ This command selects a device register (through the Comm byte), sends
 Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
 
 
-SMBus Block Read:  i2c_smbus_read_block_data()
-==============================================
+SMBus Block Read
+================
+
+Implemented by i2c_smbus_read_block_data()
 
 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
@@ -172,8 +186,10 @@ of data is specified by the device in the Count byte.
 Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
 
 
-SMBus Block Write:  i2c_smbus_write_block_data()
-================================================
+SMBus Block Write
+=================
+
+Implemented by i2c_smbus_write_block_data()
 
 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
@@ -274,8 +290,10 @@ I2C block transactions do not limit the number of bytes transferred
 but the SMBus layer places a limit of 32 bytes.
 
 
-I2C Block Read:  i2c_smbus_read_i2c_block_data()
-================================================
+I2C Block Read
+==============
+
+Implemented by 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::
@@ -286,8 +304,10 @@ designated register that is specified through the Comm byte::
 Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
 
 
-I2C Block Write:  i2c_smbus_write_i2c_block_data()
-==================================================
+I2C Block Write
+===============
+
+Implemented by i2c_smbus_write_i2c_block_data()
 
 The opposite of the Block Read command, this writes bytes to
 a device, to a designated register that is specified through the
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 16/26] docs: i2c: smbus-protocol: fix kernel-doc function syntax
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (13 preceding siblings ...)
  2020-01-05 22:50   ` [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax Luca Ceresoli
@ 2020-01-05 22:50   ` Luca Ceresoli
  2020-01-20 14:51     ` Jean Delvare
  2020-01-05 22:50   ` [PATCH 17/26] docs: i2c: i2c-protocol: fix typo Luca Ceresoli
                     ` (7 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:50 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

This clarifies these are functions (and would/will adds a hyperlink to the
function documentation if/when documented).

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/smbus-protocol.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index 997945e90419..3c0fb3a2044d 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -118,7 +118,7 @@ byte. But this time, the data is a complete word (16 bits)::
 
 Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA
 
-Note the convenience function i2c_smbus_read_word_swapped is
+Note the convenience function i2c_smbus_read_word_swapped() is
 available for reads where the two data bytes are the other way
 around (not SMBus compliant, but very popular.)
 
@@ -152,7 +152,7 @@ specified through the Comm byte.::
 
 Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA
 
-Note the convenience function i2c_smbus_write_word_swapped is
+Note the convenience function i2c_smbus_write_word_swapped() is
 available for writes where the two data bytes are the other way
 around (not SMBus compliant, but very popular.)
 
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 17/26] docs: i2c: i2c-protocol: fix typo
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (14 preceding siblings ...)
  2020-01-05 22:50   ` [PATCH 16/26] docs: i2c: smbus-protocol: fix " Luca Ceresoli
@ 2020-01-05 22:50   ` Luca Ceresoli
  2020-01-20 15:15     ` Jean Delvare
  2020-01-05 22:50   ` [PATCH 18/26] docs: i2c: i2c-protocol: fix punctuation Luca Ceresoli
                     ` (6 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:50 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

The subject is plural, fix the verb.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/smbus-protocol.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index 3c0fb3a2044d..de7285de5e93 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -145,7 +145,7 @@ SMBus Write Word
 Implemented by 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
+of data are written to a device, to the designated register that is
 specified through the Comm byte.::
 
   S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 18/26] docs: i2c: i2c-protocol: fix punctuation
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (15 preceding siblings ...)
  2020-01-05 22:50   ` [PATCH 17/26] docs: i2c: i2c-protocol: fix typo Luca Ceresoli
@ 2020-01-05 22:50   ` Luca Ceresoli
  2020-01-20 15:16     ` Jean Delvare
  2020-01-05 22:50   ` [PATCH 19/26] docs: i2c: smbus-protocol: improve I2C Block transactions description Luca Ceresoli
                     ` (5 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:50 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Remove misplaced dot before colon.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/smbus-protocol.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index de7285de5e93..7350e4b2c2fa 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -146,7 +146,7 @@ Implemented by i2c_smbus_write_word_data()
 
 This is the opposite of the Read Word operation. 16 bits
 of data are 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
 
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 19/26] docs: i2c: smbus-protocol: improve I2C Block transactions description
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (16 preceding siblings ...)
  2020-01-05 22:50   ` [PATCH 18/26] docs: i2c: i2c-protocol: fix punctuation Luca Ceresoli
@ 2020-01-05 22:50   ` Luca Ceresoli
  2020-01-21  9:16     ` Jean Delvare
  2020-01-05 22:50   ` [PATCH 20/26] docs: i2c: instantiating-devices: fix internal hyperlink Luca Ceresoli
                     ` (4 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:50 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Clarify from the beginning what these transactions are, and specifically
how they differ from the SMBus counterparts, i.e. the lack of a Count byte.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/smbus-protocol.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index 7350e4b2c2fa..0edaf6069ac1 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -282,9 +282,10 @@ This is implemented the following way in the Linux kernel:
 I2C Block Transactions
 ======================
 
-The following I2C block transactions are supported by the
-SMBus layer and are described here for completeness.
-They are *NOT* defined by the SMBus specification.
+The following I2C block transactions are similar to the SMBus Block Read
+and Write operations, except these do not have a Count byte. They are
+supported by the SMBus layer and are described here for completeness, but
+they are *NOT* defined by the SMBus specification.
 
 I2C block transactions do not limit the number of bytes transferred
 but the SMBus layer places a limit of 32 bytes.
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 20/26] docs: i2c: instantiating-devices: fix internal hyperlink
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (17 preceding siblings ...)
  2020-01-05 22:50   ` [PATCH 19/26] docs: i2c: smbus-protocol: improve I2C Block transactions description Luca Ceresoli
@ 2020-01-05 22:50   ` Luca Ceresoli
  2020-01-21 10:07     ` Jean Delvare
  2020-01-05 22:50   ` [PATCH 21/26] docs: i2c: instantiating-devices: rearrange static instatiation Luca Ceresoli
                     ` (3 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:50 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Use ReST syntax so that a proper hyperlink is generated.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/instantiating-devices.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
index cf5d9828e823..5debaafef64d 100644
--- a/Documentation/i2c/instantiating-devices.rst
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -86,7 +86,7 @@ Method 1c: Declare the I2C devices via ACPI
 -------------------------------------------
 
 ACPI can also describe I2C devices. There is special documentation for this
-which is currently located at Documentation/firmware-guide/acpi/enumeration.rst.
+which is currently located at :doc:`../firmware-guide/acpi/enumeration` .
 
 
 Method 2: Instantiate the devices explicitly
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 21/26] docs: i2c: instantiating-devices: rearrange static instatiation
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (18 preceding siblings ...)
  2020-01-05 22:50   ` [PATCH 20/26] docs: i2c: instantiating-devices: fix internal hyperlink Luca Ceresoli
@ 2020-01-05 22:50   ` Luca Ceresoli
  2020-01-21 18:02     ` Jean Delvare
  2020-01-05 22:50   ` [PATCH 22/26] docs: i2c: instantiating-devices: use monospace for filenames Luca Ceresoli
                     ` (2 subsequent siblings)
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:50 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Among the "static" instantiation methods the "board file" method is
described first. Move it as last, since it is being replaced by the other
methods.

Also fix subsubsection heading syntax and remove the "Method 1[abc]"
prefix as the subsubsection structure clarifies the logical hierarchy.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/instantiating-devices.rst | 98 ++++++++++++---------
 1 file changed, 54 insertions(+), 44 deletions(-)

diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
index 5debaafef64d..cbcafb36b417 100644
--- a/Documentation/i2c/instantiating-devices.rst
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -9,54 +9,27 @@ reason, the kernel code must instantiate I2C devices explicitly. There are
 several ways to achieve this, depending on the context and requirements.
 
 
-Method 1a: Declare the I2C devices by bus number
-------------------------------------------------
+Method 1: Declare the I2C devices statically
+--------------------------------------------
 
 This method is appropriate when the I2C bus is a system bus as is the case
-for many embedded systems. On such systems, each I2C bus has a number
-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().
+for many embedded systems. On such systems, each I2C bus has a number which
+is known in advance. It is thus possible to pre-declare the I2C devices
+which live on this bus.
 
-Example (from omap2 h4)::
+This information is provided to the kernel in a different way on different
+architectures: device tree, ACPI or board files.
 
-  static struct i2c_board_info h4_i2c_board_info[] __initdata = {
-	{
-		I2C_BOARD_INFO("isp1301_omap", 0x2d),
-		.irq		= OMAP_GPIO_IRQ(125),
-	},
-	{	/* EEPROM on mainboard */
-		I2C_BOARD_INFO("24c01", 0x52),
-		.platform_data	= &m24c01,
-	},
-	{	/* EEPROM on cpu card */
-		I2C_BOARD_INFO("24c01", 0x57),
-		.platform_data	= &m24c01,
-	},
-  };
-
-  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
-question is registered, the I2C devices will be instantiated automatically
-by i2c-core.
+When the I2C bus in question is registered, the I2C devices will be
+instantiated automatically by i2c-core. The devices will be automatically
+unbound and destroyed when the I2C bus they sit on goes away (if ever).
 
-The devices will be automatically unbound and destroyed when the I2C bus
-they sit on goes away (if ever.)
 
+Declare the I2C devices via devicetree
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-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.
+On platforms using devicetree the declaration of I2C devices is done in
+subnodes of the master controller.
 
 Example::
 
@@ -81,14 +54,51 @@ Here, two devices are attached to the bus using a speed of 100kHz. For
 additional properties which might be needed to set up the device, please refer
 to its devicetree documentation in Documentation/devicetree/bindings/.
 
-
-Method 1c: Declare the I2C devices via ACPI
--------------------------------------------
+Declare the I2C devices via ACPI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ACPI can also describe I2C devices. There is special documentation for this
 which is currently located at :doc:`../firmware-guide/acpi/enumeration` .
 
 
+Declare the I2C devices in board files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In many embedded architectures devicetree has replaced the old hardware
+description based on board files, but the latter are still used in old
+code. Instantiating I2C devices via board files is done with an array of
+struct i2c_board_info which is registered by calling
+i2c_register_board_info().
+
+Example (from omap2 h4)::
+
+  static struct i2c_board_info h4_i2c_board_info[] __initdata = {
+	{
+		I2C_BOARD_INFO("isp1301_omap", 0x2d),
+		.irq		= OMAP_GPIO_IRQ(125),
+	},
+	{	/* EEPROM on mainboard */
+		I2C_BOARD_INFO("24c01", 0x52),
+		.platform_data	= &m24c01,
+	},
+	{	/* EEPROM on cpu card */
+		I2C_BOARD_INFO("24c01", 0x57),
+		.platform_data	= &m24c01,
+	},
+  };
+
+  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.
+
+
 Method 2: Instantiate the devices explicitly
 --------------------------------------------
 
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 22/26] docs: i2c: instantiating-devices: use monospace for filenames
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (19 preceding siblings ...)
  2020-01-05 22:50   ` [PATCH 21/26] docs: i2c: instantiating-devices: rearrange static instatiation Luca Ceresoli
@ 2020-01-05 22:50   ` Luca Ceresoli
  2020-01-22 10:08     ` Jean Delvare
  2020-01-05 22:50   ` [PATCH 23/26] docs: i2c: old-module-parameters: fix internal hyperlink Luca Ceresoli
  2020-01-20  9:08   ` [PATCH 01/26] docs: i2c: sort index logically Jean Delvare
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:50 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Use a monospace (literal) formatting for better readability of filenames.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/instantiating-devices.rst | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
index cbcafb36b417..f06d44c5b692 100644
--- a/Documentation/i2c/instantiating-devices.rst
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -224,15 +224,15 @@ In general, the kernel should know which I2C devices are connected and
 what addresses they live at. However, in certain cases, it does not, so a
 sysfs interface was added to let the user provide the information. This
 interface is made of 2 attribute files which are created in every I2C bus
-directory: new_device and delete_device. Both files are write only and you
-must write the right parameters to them in order to properly instantiate,
-respectively delete, an I2C device.
+directory: ``new_device`` and ``delete_device``. Both files are write
+only and you must write the right parameters to them in order to properly
+instantiate, respectively delete, an I2C device.
 
-File new_device takes 2 parameters: the name of the I2C device (a string)
-and the address of the I2C device (a number, typically expressed in
-hexadecimal starting with 0x, but can also be expressed in decimal.)
+File ``new_device`` takes 2 parameters: the name of the I2C device (a
+string) and the address of the I2C device (a number, typically expressed
+in hexadecimal starting with 0x, but can also be expressed in decimal.)
 
-File delete_device takes a single parameter: the address of the I2C
+File ``delete_device`` takes a single parameter: the address of the I2C
 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.
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 23/26] docs: i2c: old-module-parameters: fix internal hyperlink
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (20 preceding siblings ...)
  2020-01-05 22:50   ` [PATCH 22/26] docs: i2c: instantiating-devices: use monospace for filenames Luca Ceresoli
@ 2020-01-05 22:50   ` Luca Ceresoli
  2020-01-22 10:16     ` Jean Delvare
  2020-01-20  9:08   ` [PATCH 01/26] docs: i2c: sort index logically Jean Delvare
  22 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-05 22:50 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Use ReST syntax so that a proper hyperlink is generated.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/old-module-parameters.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
index 78a6950e5763..0503d2f0b127 100644
--- a/Documentation/i2c/old-module-parameters.rst
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -12,8 +12,7 @@ address), "force" (to forcibly attach the driver to a given device) and
 With the conversion of the I2C subsystem to the standard device driver
 binding model, it became clear that these per-module parameters were no
 longer needed, and that a centralized implementation was possible. The new,
-sysfs-based interface is described in the documentation file
-"instantiating-devices", section "Method 4: Instantiate from user-space".
+sysfs-based interface is described in :doc:`instantiating-devices`.
 
 Below is a mapping from the old module parameters to the new interface.
 
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 24/26] docs: i2c: old-module-parameters: clarify this is for obsolete kernels
  2020-01-05 22:39 [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
@ 2020-01-06  7:46 ` Luca Ceresoli
  2020-01-22 11:18   ` Jean Delvare
  2020-01-06  7:46 ` [PATCH 25/26] docs: i2c: old-module-parameters: use monospace for filenames Luca Ceresoli
                   ` (2 subsequent siblings)
  4 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-06  7:46 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

This section applies only to code for very old kernels. Avoid people
reading this unnecessarily.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/old-module-parameters.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
index 0503d2f0b127..80fb117883fd 100644
--- a/Documentation/i2c/old-module-parameters.rst
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -2,6 +2,11 @@
 I2C device driver binding control from user-space
 =================================================
 
+.. NOTE::
+   Note: this section is only relevant if you are handling some old code
+   found in kernel 2.6. If you work with more recent kernels, you can
+   safely skip this section.
+
 Up to kernel 2.6.32, many I2C drivers used helper macros provided by
 <linux/i2c.h> which created standard module parameters to let the user
 control how the driver would probe I2C buses and attach to devices. These
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 25/26] docs: i2c: old-module-parameters: use monospace for filenames
  2020-01-05 22:39 [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
  2020-01-06  7:46 ` [PATCH 24/26] docs: i2c: old-module-parameters: clarify this is for obsolete kernels Luca Ceresoli
@ 2020-01-06  7:46 ` Luca Ceresoli
  2020-01-22 11:45   ` Jean Delvare
  2020-01-06  7:49 ` [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer Luca Ceresoli
  2020-01-06  8:03 ` [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
  4 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-06  7:46 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Use a monospace (literal) formatting for better readability of filenames.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/old-module-parameters.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
index 80fb117883fd..fdc470a5f999 100644
--- a/Documentation/i2c/old-module-parameters.rst
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -10,9 +10,9 @@ I2C device driver binding control from user-space
 Up to kernel 2.6.32, many I2C drivers used helper macros provided by
 <linux/i2c.h> which created standard module parameters to let the user
 control how the driver would probe I2C buses and attach to devices. These
-parameters were known as "probe" (to let the driver probe for an extra
-address), "force" (to forcibly attach the driver to a given device) and
-"ignore" (to prevent a driver from probing a given address).
+parameters were known as ``probe`` (to let the driver probe for an extra
+address), ``force`` (to forcibly attach the driver to a given device) and
+``ignore`` (to prevent a driver from probing a given address).
 
 With the conversion of the I2C subsystem to the standard device driver
 binding model, it became clear that these per-module parameters were no
@@ -46,8 +46,8 @@ New method (sysfs interface)::
   # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
   # modprobe <driver>
 
-Of course, it is important to instantiate the "dummy" device before loading
+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
 other drivers from binding to it later on. If there is a real device at the
 problematic address, and you want another driver to bind to it, then simply
-pass the name of the device in question instead of "dummy".
+pass the name of the device in question instead of ``dummy``.
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer
  2020-01-05 22:39 [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
                   ` (2 preceding siblings ...)
  2020-01-06  7:46 ` [PATCH 25/26] docs: i2c: old-module-parameters: use monospace for filenames Luca Ceresoli
@ 2020-01-06  7:49 ` Luca Ceresoli
  2020-01-07 10:36   ` Peter Rosin
  2020-01-16  9:49   ` Jean Delvare
  2020-01-06  8:03 ` [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
  4 siblings, 2 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-06  7:49 UTC (permalink / raw)
  To: linux-doc, linux-i2c
  Cc: Luca Ceresoli, Wolfram Sang, Peter Rosin, linux-kernel

Some of the section names are not very clear. Reading those names in the
index.rst page does not help much in grasping what the content is supposed
to be.

Rename those sections to clarify their content, especially when reading
the index page.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>

---

Note: here checkpatch complains:

  WARNING: Missing or malformed SPDX-License-Identifier tag in line 1

Thas's because those files have no license line. I would gladly add a
proper license line, but what it the correct license here? Should I ask the
authors? GPLv2-only as the kernel default?

I'd appreciate a guidance here, thanks in advance.
---
 Documentation/i2c/dev-interface.rst         | 6 +++---
 Documentation/i2c/i2c-protocol.rst          | 6 +++---
 Documentation/i2c/i2c-topology.rst          | 6 +++---
 Documentation/i2c/old-module-parameters.rst | 6 +++---
 Documentation/i2c/smbus-protocol.rst        | 6 +++---
 Documentation/i2c/summary.rst               | 6 +++---
 Documentation/i2c/writing-clients.rst       | 6 +++---
 7 files changed, 21 insertions(+), 21 deletions(-)

diff --git a/Documentation/i2c/dev-interface.rst b/Documentation/i2c/dev-interface.rst
index c3717a87df12..bdb247f2f11a 100644
--- a/Documentation/i2c/dev-interface.rst
+++ b/Documentation/i2c/dev-interface.rst
@@ -1,6 +1,6 @@
-====================
-I2C Device Interface
-====================
+============================================
+Implementing I2C device drivers in userspace
+============================================
 
 Usually, I2C devices are controlled by a kernel driver. But it is also
 possible to access all devices on an adapter from userspace, through
diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst
index 9a4ac944cf9d..6aafc3880bce 100644
--- a/Documentation/i2c/i2c-protocol.rst
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -1,6 +1,6 @@
-============
-I2C Protocol
-============
+================
+The I2C Protocol
+================
 
 This document describes the I2C protocol. Or will, when it is finished :-)
 
diff --git a/Documentation/i2c/i2c-topology.rst b/Documentation/i2c/i2c-topology.rst
index 2a18b53e3508..7cb53819778e 100644
--- a/Documentation/i2c/i2c-topology.rst
+++ b/Documentation/i2c/i2c-topology.rst
@@ -1,6 +1,6 @@
-============
-I2C topology
-============
+================================
+I2C muxes and complex topologies
+================================
 
 There are a couple of reasons for building more complex I2C topologies
 than a straight-forward I2C bus with one adapter and one or more devices.
diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
index fdc470a5f999..f64d3cebc9a1 100644
--- a/Documentation/i2c/old-module-parameters.rst
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -1,6 +1,6 @@
-=================================================
-I2C device driver binding control from user-space
-=================================================
+================================================================
+I2C device driver binding control from user-space in old kernels
+================================================================
 
 .. NOTE::
    Note: this section is only relevant if you are handling some old code
diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index 0edaf6069ac1..c122ed239f7f 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -1,6 +1,6 @@
-======================
-SMBus Protocol Summary
-======================
+==================
+The SMBus Protocol
+==================
 
 The following is a summary of the SMBus protocol. It applies to
 all revisions of the protocol (1.0, 1.1, and 2.0).
diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
index fc69d9567d9d..ae3bbb9fd8f1 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -1,6 +1,6 @@
-=============
-I2C and SMBus
-=============
+==============================
+Introductions to I2C and SMBus
+==============================
 
 I²C (pronounce: I squared C and written I2C in the kernel documentation) is
 a protocol developed by Philips. It is a slow two-wire protocol (variable
diff --git a/Documentation/i2c/writing-clients.rst b/Documentation/i2c/writing-clients.rst
index 1bf4b973c673..5eddf20e983e 100644
--- a/Documentation/i2c/writing-clients.rst
+++ b/Documentation/i2c/writing-clients.rst
@@ -1,6 +1,6 @@
-===================
-Writing I2C Clients
-===================
+===============================
+Implementing I2C device drivers
+===============================
 
 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).
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 72+ messages in thread

* Re: [PATCH 00/26] docs: i2c: rework I2C documentation, part I
  2020-01-05 22:39 [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
                   ` (3 preceding siblings ...)
  2020-01-06  7:49 ` [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer Luca Ceresoli
@ 2020-01-06  8:03 ` Luca Ceresoli
  4 siblings, 0 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-06  8:03 UTC (permalink / raw)
  To: linux-doc, linux-i2c; +Cc: Wolfram Sang, Peter Rosin, linux-kernel

Hi,

my apologies for the incorrect threading of these e-mails. I've been
having troubles while sending them out, so I had to resend them manually
in chunks and while doing that I didn't manage to recreate the proper
threading.

-- 
Luca

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 04/26] docs: i2c: call it "I2C" consistently
  2020-01-05 22:49   ` [PATCH 04/26] docs: i2c: call it "I2C" consistently Luca Ceresoli
@ 2020-01-07 10:33     ` Peter Rosin
  2020-01-16  9:39     ` Jean Delvare
  1 sibling, 0 replies; 72+ messages in thread
From: Peter Rosin @ 2020-01-07 10:33 UTC (permalink / raw)
  To: Luca Ceresoli, linux-doc, linux-i2c; +Cc: Wolfram Sang, linux-kernel

On 2020-01-05 23:49, Luca Ceresoli wrote:
> Uppercase "I2C" is used almost everywhere in the docs, but the lowercase
> version "i2c" is used somewhere. Use the uppercase form consistently.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>

Acked-by: Peter Rosin <peda@axentia.se>

Cheers,
Peter

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 05/26] docs: i2c: fix typo
  2020-01-05 22:49   ` [PATCH 05/26] docs: i2c: fix typo Luca Ceresoli
@ 2020-01-07 10:33     ` Peter Rosin
  2020-01-16  9:40     ` Jean Delvare
  1 sibling, 0 replies; 72+ messages in thread
From: Peter Rosin @ 2020-01-07 10:33 UTC (permalink / raw)
  To: Luca Ceresoli, linux-doc, linux-i2c; +Cc: Wolfram Sang, linux-kernel

On 2020-01-05 23:49, Luca Ceresoli wrote:
> Fix "issus" -> "issues".
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>

Acked-by: Peter Rosin <peda@axentia.se>

Cheers,
Peter


^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 06/26] docs: i2c: replace "I2C-transfer" -> "I2C transfer" consistently
  2020-01-05 22:49   ` [PATCH 06/26] docs: i2c: replace "I2C-transfer" -> "I2C transfer" consistently Luca Ceresoli
@ 2020-01-07 10:34     ` Peter Rosin
  2020-01-20 10:07     ` Jean Delvare
  1 sibling, 0 replies; 72+ messages in thread
From: Peter Rosin @ 2020-01-07 10:34 UTC (permalink / raw)
  To: Luca Ceresoli, linux-doc, linux-i2c; +Cc: Wolfram Sang, linux-kernel

On 2020-01-05 23:49, Luca Ceresoli wrote:
> "I2C transfer" is a legitimate english sentence, no need for a hyphen
> between the two words, as as such it is used in most of the
> documentation. Remove the hyphen in the few places where it is present.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>

Acked-by: Peter Rosin <peda@axentia.se>

Cheers,
Peter


^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer
  2020-01-06  7:49 ` [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer Luca Ceresoli
@ 2020-01-07 10:36   ` Peter Rosin
  2020-01-16  9:49   ` Jean Delvare
  1 sibling, 0 replies; 72+ messages in thread
From: Peter Rosin @ 2020-01-07 10:36 UTC (permalink / raw)
  To: Luca Ceresoli, linux-doc, linux-i2c; +Cc: Wolfram Sang, linux-kernel

On 2020-01-06 08:49, Luca Ceresoli wrote:
> Some of the section names are not very clear. Reading those names in the
> index.rst page does not help much in grasping what the content is supposed
> to be.
> 
> Rename those sections to clarify their content, especially when reading
> the index page.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>

Acked-by: Peter Rosin <peda@axentia.se>

Cheers,
Peter


^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 04/26] docs: i2c: call it "I2C" consistently
  2020-01-05 22:49   ` [PATCH 04/26] docs: i2c: call it "I2C" consistently Luca Ceresoli
  2020-01-07 10:33     ` Peter Rosin
@ 2020-01-16  9:39     ` Jean Delvare
  1 sibling, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-16  9:39 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:50 +0100, Luca Ceresoli wrote:
> Uppercase "I2C" is used almost everywhere in the docs, but the lowercase
> version "i2c" is used somewhere. Use the uppercase form consistently.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> Acked-by: Peter Rosin <peda@axentia.se>
> ---
>  Documentation/i2c/dev-interface.rst         | 18 +++---
>  Documentation/i2c/dma-considerations.rst    |  2 +-
>  Documentation/i2c/i2c-protocol.rst          |  4 +-
>  Documentation/i2c/i2c-topology.rst          | 66 ++++++++++-----------
>  Documentation/i2c/instantiating-devices.rst |  2 +-
>  Documentation/i2c/old-module-parameters.rst |  6 +-
>  Documentation/i2c/slave-interface.rst       |  4 +-
>  Documentation/i2c/writing-clients.rst       |  4 +-
>  8 files changed, 53 insertions(+), 53 deletions(-)
> (...)

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 05/26] docs: i2c: fix typo
  2020-01-05 22:49   ` [PATCH 05/26] docs: i2c: fix typo Luca Ceresoli
  2020-01-07 10:33     ` Peter Rosin
@ 2020-01-16  9:40     ` Jean Delvare
  1 sibling, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-16  9:40 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:51 +0100, Luca Ceresoli wrote:
> Fix "issus" -> "issues".
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> Acked-by: Peter Rosin <peda@axentia.se>
> ---
>  Documentation/i2c/i2c-topology.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/i2c/i2c-topology.rst b/Documentation/i2c/i2c-topology.rst
> index 0875090d6aeb..b413ef6a6773 100644
> --- a/Documentation/i2c/i2c-topology.rst
> +++ b/Documentation/i2c/i2c-topology.rst
> @@ -169,7 +169,7 @@ 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
>       and the actual transfer (e.g. if the child mux is auto-closing
> -     and the parent mux issus I2C-transfers as part of its select).
> +     and the parent mux issues I2C-transfers as part of its select).
>       This is especially the case if the parent mux is mux-locked, but
>       it may also happen if the parent mux is parent-locked.
>  

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer
  2020-01-06  7:49 ` [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer Luca Ceresoli
  2020-01-07 10:36   ` Peter Rosin
@ 2020-01-16  9:49   ` Jean Delvare
  2020-01-16 10:38     ` Luca Ceresoli
  1 sibling, 1 reply; 72+ messages in thread
From: Jean Delvare @ 2020-01-16  9:49 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Mon,  6 Jan 2020 08:49:05 +0100, Luca Ceresoli wrote:
> Some of the section names are not very clear. Reading those names in the
> index.rst page does not help much in grasping what the content is supposed
> to be.
> 
> Rename those sections to clarify their content, especially when reading
> the index page.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> Acked-by: Peter Rosin <peda@axentia.se>
> ---
> 
> Note: here checkpatch complains:
> 
>   WARNING: Missing or malformed SPDX-License-Identifier tag in line 1
> 
> Thas's because those files have no license line. I would gladly add a
> proper license line, but what it the correct license here? Should I ask the
> authors? GPLv2-only as the kernel default?
> 
> I'd appreciate a guidance here, thanks in advance.

I don't think we need a license for such documentation files, so I
would just ignore checkpatch.

> ---
>  Documentation/i2c/dev-interface.rst         | 6 +++---
>  Documentation/i2c/i2c-protocol.rst          | 6 +++---
>  Documentation/i2c/i2c-topology.rst          | 6 +++---
>  Documentation/i2c/old-module-parameters.rst | 6 +++---
>  Documentation/i2c/smbus-protocol.rst        | 6 +++---
>  Documentation/i2c/summary.rst               | 6 +++---
>  Documentation/i2c/writing-clients.rst       | 6 +++---
>  7 files changed, 21 insertions(+), 21 deletions(-)
> (...)
> diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
> index fc69d9567d9d..ae3bbb9fd8f1 100644
> --- a/Documentation/i2c/summary.rst
> +++ b/Documentation/i2c/summary.rst
> @@ -1,6 +1,6 @@
> -=============
> -I2C and SMBus
> -=============
> +==============================
> +Introductions to I2C and SMBus
> +==============================

I would use "Introduction", singular.

>  
>  I²C (pronounce: I squared C and written I2C in the kernel documentation) is
>  a protocol developed by Philips. It is a slow two-wire protocol (variable
> (...)

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer
  2020-01-16  9:49   ` Jean Delvare
@ 2020-01-16 10:38     ` Luca Ceresoli
  2020-01-16 13:34       ` Peter Rosin
  0 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-16 10:38 UTC (permalink / raw)
  To: Jean Delvare
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

Hi Jean, Peter,

thanks both for your reviews.

On 16/01/20 10:49, Jean Delvare wrote:
> On Mon,  6 Jan 2020 08:49:05 +0100, Luca Ceresoli wrote:
>> Some of the section names are not very clear. Reading those names in the
>> index.rst page does not help much in grasping what the content is supposed
>> to be.
>>
>> Rename those sections to clarify their content, especially when reading
>> the index page.
>>
>> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
>> Acked-by: Peter Rosin <peda@axentia.se>
>> ---
>>
>> Note: here checkpatch complains:
>>
>>   WARNING: Missing or malformed SPDX-License-Identifier tag in line 1
>>
>> Thas's because those files have no license line. I would gladly add a
>> proper license line, but what it the correct license here? Should I ask the
>> authors? GPLv2-only as the kernel default?
>>
>> I'd appreciate a guidance here, thanks in advance.
> 
> I don't think we need a license for such documentation files, so I
> would just ignore checkpatch.

That's OK for me.

>> diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
>> index fc69d9567d9d..ae3bbb9fd8f1 100644
>> --- a/Documentation/i2c/summary.rst
>> +++ b/Documentation/i2c/summary.rst
>> @@ -1,6 +1,6 @@
>> -=============
>> -I2C and SMBus
>> -=============
>> +==============================
>> +Introductions to I2C and SMBus
>> +==============================
> 
> I would use "Introduction", singular.

Me too! Fix queued for v2.

Peter, I assume I can keep your Acked-by in v2 with this small change.

-- 
Luca

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer
  2020-01-16 10:38     ` Luca Ceresoli
@ 2020-01-16 13:34       ` Peter Rosin
  0 siblings, 0 replies; 72+ messages in thread
From: Peter Rosin @ 2020-01-16 13:34 UTC (permalink / raw)
  To: Luca Ceresoli, Jean Delvare
  Cc: linux-doc, linux-i2c, Wolfram Sang, linux-kernel

On 2020-01-16 11:38, Luca Ceresoli wrote:
> Hi Jean, Peter,
> 
> thanks both for your reviews.
> 
> On 16/01/20 10:49, Jean Delvare wrote:
>> On Mon,  6 Jan 2020 08:49:05 +0100, Luca Ceresoli wrote:
>>> Some of the section names are not very clear. Reading those names in the
>>> index.rst page does not help much in grasping what the content is supposed
>>> to be.
>>>
>>> Rename those sections to clarify their content, especially when reading
>>> the index page.
>>>
>>> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
>>> Acked-by: Peter Rosin <peda@axentia.se>
>>> ---
>>>
>>> Note: here checkpatch complains:
>>>
>>>   WARNING: Missing or malformed SPDX-License-Identifier tag in line 1
>>>
>>> Thas's because those files have no license line. I would gladly add a
>>> proper license line, but what it the correct license here? Should I ask the
>>> authors? GPLv2-only as the kernel default?
>>>
>>> I'd appreciate a guidance here, thanks in advance.
>>
>> I don't think we need a license for such documentation files, so I
>> would just ignore checkpatch.
> 
> That's OK for me.
> 
>>> diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
>>> index fc69d9567d9d..ae3bbb9fd8f1 100644
>>> --- a/Documentation/i2c/summary.rst
>>> +++ b/Documentation/i2c/summary.rst
>>> @@ -1,6 +1,6 @@
>>> -=============
>>> -I2C and SMBus
>>> -=============
>>> +==============================
>>> +Introductions to I2C and SMBus
>>> +==============================
>>
>> I would use "Introduction", singular.
> 
> Me too! Fix queued for v2.
> 
> Peter, I assume I can keep your Acked-by in v2 with this small change.

That's fine.

Cheers,
Peter

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 01/26] docs: i2c: sort index logically
  2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
                     ` (21 preceding siblings ...)
  2020-01-05 22:50   ` [PATCH 23/26] docs: i2c: old-module-parameters: fix internal hyperlink Luca Ceresoli
@ 2020-01-20  9:08   ` Jean Delvare
  2020-01-20  9:22     ` Luca Ceresoli
  22 siblings, 1 reply; 72+ messages in thread
From: Jean Delvare @ 2020-01-20  9:08 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

Hi Luca,

On Sun,  5 Jan 2020 23:49:47 +0100, Luca Ceresoli wrote:
> The index page currently lists sections in alphabetical file order without
> caring about their content. Sort sections based on their content logically,
> according to the following structure:
> 
>  * Intro to I2C/SMBus and their usage in Linux: summary, i2c-protocol,
>    smbus-protocol, instantiating-devices, busses/index, i2c-topology,
>    muxes/i2c-mux-gpio
>  * Implementing drivers: writing-clients, dev-interface,
>    dma-considerations, fault-codes, functionality
>  * Debugging: gpio-fault-injection, i2c-stub
>  * Slave I2C: slave-interface, slave-eeprom-backend
>  * Advanced: ten-bit-addresses
>  * Obsolete info: upgrading-clients, old-module-parameters

Good idea. I wonder, would there be a way to materialize these group
names in the documentation itself? I found it useful when reviewing the
patch, but in the long term it would be even more useful if the end
readers would see them too.

> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/index.rst | 21 ++++++++++-----------
>  1 file changed, 10 insertions(+), 11 deletions(-)
> 
> diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
> index a0fbaf6d0675..bd0ff9d00793 100644
> --- a/Documentation/i2c/index.rst
> +++ b/Documentation/i2c/index.rst
> @@ -7,27 +7,26 @@ I2C/SMBus Subsystem
>  .. toctree::
>     :maxdepth: 1
>  
> +   summary
> +   i2c-protocol
> +   smbus-protocol
> +   instantiating-devices
> +   busses/index
> +   i2c-topology
> +   muxes/i2c-mux-gpio
> +   writing-clients
>     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
> +   slave-eeprom-backend
>     ten-bit-addresses
>     upgrading-clients
> -   writing-clients
> -
> -   muxes/i2c-mux-gpio
> +   old-module-parameters
>  
> -   busses/index
>  

You end up with 2 blank lines in a row here, ideally there should be
only one left.

>  .. only::  subproject and html
>  

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 01/26] docs: i2c: sort index logically
  2020-01-20  9:08   ` [PATCH 01/26] docs: i2c: sort index logically Jean Delvare
@ 2020-01-20  9:22     ` Luca Ceresoli
  2020-01-20 13:56       ` Luca Ceresoli
  0 siblings, 1 reply; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-20  9:22 UTC (permalink / raw)
  To: Jean Delvare
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

Hi Jean,

On 20/01/20 10:08, Jean Delvare wrote:
> Hi Luca,
> 
> On Sun,  5 Jan 2020 23:49:47 +0100, Luca Ceresoli wrote:
>> The index page currently lists sections in alphabetical file order without
>> caring about their content. Sort sections based on their content logically,
>> according to the following structure:
>>
>>  * Intro to I2C/SMBus and their usage in Linux: summary, i2c-protocol,
>>    smbus-protocol, instantiating-devices, busses/index, i2c-topology,
>>    muxes/i2c-mux-gpio
>>  * Implementing drivers: writing-clients, dev-interface,
>>    dma-considerations, fault-codes, functionality
>>  * Debugging: gpio-fault-injection, i2c-stub
>>  * Slave I2C: slave-interface, slave-eeprom-backend
>>  * Advanced: ten-bit-addresses
>>  * Obsolete info: upgrading-clients, old-module-parameters
> 
> Good idea. I wonder, would there be a way to materialize these group
> names in the documentation itself? I found it useful when reviewing the
> patch, but in the long term it would be even more useful if the end
> readers would see them too.

I had the same idea, but didn't find an obvious way to do it with the
ReST/Sphynx syntax. I have also browsed through a few index pages for
other subsystems and they all have a flat list too, so for the moment I
gave up.

Anybody has hints on how to do this in a clean way?

>> diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
>> index a0fbaf6d0675..bd0ff9d00793 100644
>> --- a/Documentation/i2c/index.rst
>> +++ b/Documentation/i2c/index.rst
>> @@ -7,27 +7,26 @@ I2C/SMBus Subsystem
>>  .. toctree::
>>     :maxdepth: 1
>>  
>> +   summary
>> +   i2c-protocol
>> +   smbus-protocol
>> +   instantiating-devices
>> +   busses/index
>> +   i2c-topology
>> +   muxes/i2c-mux-gpio
>> +   writing-clients
>>     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
>> +   slave-eeprom-backend
>>     ten-bit-addresses
>>     upgrading-clients
>> -   writing-clients
>> -
>> -   muxes/i2c-mux-gpio
>> +   old-module-parameters
>>  
>> -   busses/index
>>  
> 
> You end up with 2 blank lines in a row here, ideally there should be
> only one left.

Good catch, thanks, will fix in v2.

-- 
Luca

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 02/26] docs: i2c: summary: extend introduction
  2020-01-05 22:49   ` [PATCH 02/26] docs: i2c: summary: extend introduction Luca Ceresoli
@ 2020-01-20  9:27     ` Jean Delvare
  2020-01-20 21:54       ` Luca Ceresoli
  0 siblings, 1 reply; 72+ messages in thread
From: Jean Delvare @ 2020-01-20  9:27 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:48 +0100, Luca Ceresoli wrote:
> - state the "official" name (I²C, not I2C, according to the spec) at
>    the beginning but keep using the more practical I2C elsewhere
>  - mention some known different names
>  - add link to the specification document

Indentation is inconsistent.

> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/summary.rst | 18 ++++++++++++------
>  1 file changed, 12 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
> index 3a24eac17375..b7d3e620155b 100644
> --- a/Documentation/i2c/summary.rst
> +++ b/Documentation/i2c/summary.rst
> @@ -2,12 +2,18 @@
>  I2C and SMBus
>  =============
>  
> -I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
> -slow two-wire protocol (variable speed, up to 400 kHz), with a high speed
> -extension (3.4 MHz).  It provides an inexpensive bus for connecting many
> -types of devices with infrequent or low bandwidth communications needs.
> -I2C is widely used with embedded systems.  Some systems use variants that
> -don't meet branding requirements, and so are not advertised as being I2C.
> +I²C (pronounce: I squared C and written I2C in the kernel documentation) is
> +a protocol developed by Philips. It is a slow two-wire protocol (variable
> +speed, up to 400 kHz), with a high speed extension (3.4 MHz).  It provides
> +an inexpensive bus for connecting many types of devices with infrequent or
> +low bandwidth communications needs.  I2C is widely used with embedded
> +systems.  Some systems use variants that don't meet branding requirements,
> +and so are not advertised as being I2C but with different names, e.g. TWI
> +(Two Wire Interface), IIC.

Maybe that's just me but "but with different names" sounds strange to
me in the sentence construct. Maybe "but come under different names"
instead?

> +
> +The official I2C specification is the `"I2C-bus specification and user
> +manual" (UM10204) <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_
> +published by NXP Semiconductors.
>  
>  SMBus (System Management Bus) is based on the I2C protocol, and is mostly
>  a subset of I2C protocols and signaling.  Many I2C devices will work on an

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 03/26] docs: i2c: summary: rewrite the "terminology" section
  2020-01-05 22:49   ` [PATCH 03/26] docs: i2c: summary: rewrite the "terminology" section Luca Ceresoli
@ 2020-01-20 10:04     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 10:04 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:49 +0100, Luca Ceresoli wrote:
> This section, partly dating back to the pre-git era, is somewhat
> unclear and partly incorrect. Rewrite it almost completely including a
> reference figure, concise but precise definition of each term and the
> paths where drivers are found. Particular care has been put in clarifying
> the relation between adapter and algorithm, which has no correspondence
> in the I2C spec terminology.

It may make sense to mention path "drivers/i2c/algos/" in the paragraph
which mentions reusable algorithms.

> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/i2c.svg     | 1341 +++++++++++++++++++++++++++++++++
>  Documentation/i2c/summary.rst |   35 +-
>  2 files changed, 1362 insertions(+), 14 deletions(-)
>  create mode 100644 Documentation/i2c/i2c.svg
> (...)

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 06/26] docs: i2c: replace "I2C-transfer" -> "I2C transfer" consistently
  2020-01-05 22:49   ` [PATCH 06/26] docs: i2c: replace "I2C-transfer" -> "I2C transfer" consistently Luca Ceresoli
  2020-01-07 10:34     ` Peter Rosin
@ 2020-01-20 10:07     ` Jean Delvare
  1 sibling, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 10:07 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:52 +0100, Luca Ceresoli wrote:
> "I2C transfer" is a legitimate english sentence, no need for a hyphen
> between the two words, as as such it is used in most of the
> documentation. Remove the hyphen in the few places where it is present.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> Acked-by: Peter Rosin <peda@axentia.se>
> ---
>  Documentation/i2c/i2c-topology.rst | 24 ++++++++++++------------
>  1 file changed, 12 insertions(+), 12 deletions(-)
> (...)

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 07/26] docs: i2c: i2c-protocol: fix kernel-doc function syntax
  2020-01-05 22:49   ` [PATCH 07/26] docs: i2c: i2c-protocol: fix kernel-doc function syntax Luca Ceresoli
@ 2020-01-20 10:51     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 10:51 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:53 +0100, Luca Ceresoli wrote:
> This clarifies these are functions and adds a hyperlink to the function
> documentation.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/i2c-protocol.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> (...)

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 08/26] docs: i2c: i2c-protocol: properly name start and stop conditions
  2020-01-05 22:49   ` [PATCH 08/26] docs: i2c: i2c-protocol: properly name start and stop conditions Luca Ceresoli
@ 2020-01-20 12:49     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 12:49 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:54 +0100, Luca Ceresoli wrote:
> In I2C there is no such thing as a "start bit" or a "stop bit". Use the
> proper naming: "start condition" and "stop condition".
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/i2c-protocol.rst | 15 ++++++++-------
>  1 file changed, 8 insertions(+), 7 deletions(-)
> (...)

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 09/26] docs: i2c: i2c-protocol: remove unneeded colons from table
  2020-01-05 22:49   ` [PATCH 09/26] docs: i2c: i2c-protocol: remove unneeded colons from table Luca Ceresoli
@ 2020-01-20 13:38     ` Jean Delvare
  2020-01-20 14:22       ` Jean Delvare
  0 siblings, 1 reply; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 13:38 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:55 +0100, Luca Ceresoli wrote:
> These colons are not needed: the columns already nicely separate the
> symbold from their description. They are also inconsistently preceded by
> whitespace.
> 
> Remove the colons completely to simplify and clean up.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/i2c-protocol.rst | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
> (...)

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 10/26] docs: i2c: i2c-protocol: use proper names for ACK and NACK
  2020-01-05 22:49   ` [PATCH 10/26] docs: i2c: i2c-protocol: use proper names for ACK and NACK Luca Ceresoli
@ 2020-01-20 13:50     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 13:50 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:56 +0100, Luca Ceresoli wrote:
> Use the proper ACK and NACK naming from the I2C specification instead of
> "accept" and "reverse accept".
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/i2c-protocol.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst
> index 66adac3a5afd..9a4ac944cf9d 100644
> --- a/Documentation/i2c/i2c-protocol.rst
> +++ b/Documentation/i2c/i2c-protocol.rst
> @@ -11,7 +11,7 @@ Key to symbols
>  S               Start condition
>  P               Stop condition
>  Rd/Wr (1 bit)   Read/Write bit. Rd equals 1, Wr equals 0.
> -A, NA (1 bit)   Accept and reverse accept bit.
> +A, NA (1 bit)   Acknowledge (ACK) and Not Acknowledge (NACK) bit
>  Addr  (7 bits)  I2C 7 bit address. Note that this can be expanded as usual to
>                  get a 10 bit I2C address.
>  Comm  (8 bits)  Command byte, a data byte which often selects a register on

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 01/26] docs: i2c: sort index logically
  2020-01-20  9:22     ` Luca Ceresoli
@ 2020-01-20 13:56       ` Luca Ceresoli
  0 siblings, 0 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-20 13:56 UTC (permalink / raw)
  To: Jean Delvare
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

Hi,

On 20/01/20 10:22, Luca Ceresoli wrote:
> Hi Jean,
> 
> On 20/01/20 10:08, Jean Delvare wrote:
>> Hi Luca,
>>
>> On Sun,  5 Jan 2020 23:49:47 +0100, Luca Ceresoli wrote:
>>> The index page currently lists sections in alphabetical file order without
>>> caring about their content. Sort sections based on their content logically,
>>> according to the following structure:
>>>
>>>  * Intro to I2C/SMBus and their usage in Linux: summary, i2c-protocol,
>>>    smbus-protocol, instantiating-devices, busses/index, i2c-topology,
>>>    muxes/i2c-mux-gpio
>>>  * Implementing drivers: writing-clients, dev-interface,
>>>    dma-considerations, fault-codes, functionality
>>>  * Debugging: gpio-fault-injection, i2c-stub
>>>  * Slave I2C: slave-interface, slave-eeprom-backend
>>>  * Advanced: ten-bit-addresses
>>>  * Obsolete info: upgrading-clients, old-module-parameters
>>
>> Good idea. I wonder, would there be a way to materialize these group
>> names in the documentation itself? I found it useful when reviewing the
>> patch, but in the long term it would be even more useful if the end
>> readers would see them too.
> 
> I had the same idea, but didn't find an obvious way to do it with the
> ReST/Sphynx syntax. I have also browsed through a few index pages for
> other subsystems and they all have a flat list too, so for the moment I
> gave up.

The best way I could find is in Documentation/core-api/index.rst
(https://www.kernel.org/doc/html/latest/core-api/index.html). I don't
like very much how the .rst source looks like, but AFAICT this seems
like "the" way of doing it.

Unless there are better options, I'll try this syntax in v2.

-- 
Luca

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 11/26] docs: i2c: smbus: fix link syntax
  2020-01-05 22:49   ` [PATCH 11/26] docs: i2c: smbus: fix link syntax Luca Ceresoli
@ 2020-01-20 14:10     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 14:10 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:57 +0100, Luca Ceresoli wrote:
> Use the proper ReST syntax to generate a valid hyperlink.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/smbus-protocol.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
> index e30eb1d274c6..1600b09ec0be 100644
> --- a/Documentation/i2c/smbus-protocol.rst
> +++ b/Documentation/i2c/smbus-protocol.rst
> @@ -27,8 +27,8 @@ a different protocol operation entirely.
>  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.rst> for the details.
> +adapter supports the transaction in question. See :doc:`functionality` for
> +the details.
>  
>  
>  Key to symbols

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 12/26] docs: i2c: smbus-protocol: properly name start and stop conditions
  2020-01-05 22:49   ` [PATCH 12/26] docs: i2c: smbus-protocol: properly name start and stop conditions Luca Ceresoli
@ 2020-01-20 14:16     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 14:16 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:58 +0100, Luca Ceresoli wrote:
> In I2C there is no such thing as a "start bit" or a "stop bit". Use the
> proper naming: "start condition" and "stop condition".
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/smbus-protocol.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
> index 1600b09ec0be..8510eeda1dd0 100644
> --- a/Documentation/i2c/smbus-protocol.rst
> +++ b/Documentation/i2c/smbus-protocol.rst
> @@ -35,8 +35,8 @@ Key to symbols
>  ==============
>  
>  =============== =============================================================
> -S     (1 bit) : Start bit
> -P     (1 bit) : Stop bit
> +S             : Start condition
> +P             : Stop condition
>  Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
>  A, NA (1 bit) : Accept and reverse accept bit.
>  Addr  (7 bits): I2C 7 bit address. Note that this can be expanded as usual to

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 09/26] docs: i2c: i2c-protocol: remove unneeded colons from table
  2020-01-20 13:38     ` Jean Delvare
@ 2020-01-20 14:22       ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 14:22 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

Ah, actually...

On Mon, 20 Jan 2020 14:38:52 +0100, Jean Delvare wrote:
> On Sun,  5 Jan 2020 23:49:55 +0100, Luca Ceresoli wrote:
> > These colons are not needed: the columns already nicely separate the
> > symbold from their description. They are also inconsistently preceded by

... you have a typo there, s/symbold/symbols/.

> > whitespace.
> > 
> > Remove the colons completely to simplify and clean up.
> > 
> > Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> > ---
> >  Documentation/i2c/i2c-protocol.rst | 18 +++++++++---------
> >  1 file changed, 9 insertions(+), 9 deletions(-)
> > (...)  
> 
> Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 13/26] docs: i2c: smbus-protocol: remove unneeded colons from table
  2020-01-05 22:49   ` [PATCH 13/26] docs: i2c: smbus-protocol: remove unneeded colons from table Luca Ceresoli
@ 2020-01-20 14:23     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 14:23 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:49:59 +0100, Luca Ceresoli wrote:
> These colons are not needed: the columns already nicely separate the
> symbold from their description. They are also inconsistently preceded by
> whitespace.

s/symbold/symbols/

> 
> Remove the colons completely to simplify and clean up.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/smbus-protocol.rst | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
> (...)

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 14/26] docs: i2c: smbus-protocol: use proper names for ACK and NACK
  2020-01-05 22:50   ` [PATCH 14/26] docs: i2c: smbus-protocol: use proper names for ACK and NACK Luca Ceresoli
@ 2020-01-20 14:26     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 14:26 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:50:00 +0100, Luca Ceresoli wrote:
> Use the proper ACK and NACK naming from the I2C specification instead of
> "accept" and "reverse accept".
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/smbus-protocol.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
> index fbadd4d25ad5..10c4a989982c 100644
> --- a/Documentation/i2c/smbus-protocol.rst
> +++ b/Documentation/i2c/smbus-protocol.rst
> @@ -38,7 +38,7 @@ Key to symbols
>  S               Start condition
>  P               Stop condition
>  Rd/Wr (1 bit)   Read/Write bit. Rd equals 1, Wr equals 0.
> -A, NA (1 bit)   Accept and reverse accept bit.
> +A, NA (1 bit)   Acknowledge (ACK) and Not Acknowledge (NACK) bit
>  Addr  (7 bits)  I2C 7 bit address. Note that this can be expanded as usual to
>                  get a 10 bit I2C address.
>  Comm  (8 bits)  Command byte, a data byte which often selects a register on

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax
  2020-01-05 22:50   ` [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax Luca Ceresoli
@ 2020-01-20 14:44     ` Jean Delvare
  2020-01-21 17:31       ` Luca Ceresoli
  0 siblings, 1 reply; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 14:44 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:50:01 +0100, Luca Ceresoli wrote:
> Hyperlinks from function names are not generated in headings. Move them in
> the plain text so they are rendered as clickable hyerlinks.

typo: hyperlinks

> 
> While there also remove an unneeded colon in a heading.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/smbus-protocol.rst | 64 ++++++++++++++++++----------
>  1 file changed, 42 insertions(+), 22 deletions(-)
> 
> diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
> index 10c4a989982c..997945e90419 100644
> --- a/Documentation/i2c/smbus-protocol.rst
> +++ b/Documentation/i2c/smbus-protocol.rst
> @@ -62,8 +62,10 @@ This sends a single bit to the device, at the place of the Rd/Wr bit::
>  Functionality flag: I2C_FUNC_SMBUS_QUICK
>  
>  
> -SMBus Receive Byte:  i2c_smbus_read_byte()
> -==========================================
> +SMBus Receive Byte
> +==================
> +
> +Implemented by i2c_smbus_read_byte()

In file i2c-protocol.rst, the wording used is:

This corresponds to i2c_transfer().

For consistency, can we settle for "Implemented by foo()" everywhere?

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 16/26] docs: i2c: smbus-protocol: fix kernel-doc function syntax
  2020-01-05 22:50   ` [PATCH 16/26] docs: i2c: smbus-protocol: fix " Luca Ceresoli
@ 2020-01-20 14:51     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 14:51 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:50:02 +0100, Luca Ceresoli wrote:
> This clarifies these are functions (and would/will adds a hyperlink to the
> function documentation if/when documented).
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/smbus-protocol.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
> index 997945e90419..3c0fb3a2044d 100644
> --- a/Documentation/i2c/smbus-protocol.rst
> +++ b/Documentation/i2c/smbus-protocol.rst
> @@ -118,7 +118,7 @@ byte. But this time, the data is a complete word (16 bits)::
>  
>  Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA
>  
> -Note the convenience function i2c_smbus_read_word_swapped is
> +Note the convenience function i2c_smbus_read_word_swapped() is
>  available for reads where the two data bytes are the other way
>  around (not SMBus compliant, but very popular.)
>  
> @@ -152,7 +152,7 @@ specified through the Comm byte.::
>  
>  Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA
>  
> -Note the convenience function i2c_smbus_write_word_swapped is
> +Note the convenience function i2c_smbus_write_word_swapped() is
>  available for writes where the two data bytes are the other way
>  around (not SMBus compliant, but very popular.)
>  

Reviewed-by: Jean Delvare <jdelvare@suse.de>


-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 17/26] docs: i2c: i2c-protocol: fix typo
  2020-01-05 22:50   ` [PATCH 17/26] docs: i2c: i2c-protocol: fix typo Luca Ceresoli
@ 2020-01-20 15:15     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 15:15 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

The patch's subject line is wrong, it touches smbus-protocol, not
i2c-protocol.

On Sun,  5 Jan 2020 23:50:03 +0100, Luca Ceresoli wrote:
> The subject is plural, fix the verb.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/smbus-protocol.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
> index 3c0fb3a2044d..de7285de5e93 100644
> --- a/Documentation/i2c/smbus-protocol.rst
> +++ b/Documentation/i2c/smbus-protocol.rst
> @@ -145,7 +145,7 @@ SMBus Write Word
>  Implemented by 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
> +of data are written to a device, to the designated register that is
>  specified through the Comm byte.::
>  
>    S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 18/26] docs: i2c: i2c-protocol: fix punctuation
  2020-01-05 22:50   ` [PATCH 18/26] docs: i2c: i2c-protocol: fix punctuation Luca Ceresoli
@ 2020-01-20 15:16     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-20 15:16 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

Same as previous patch, subject line is wrong.

On Sun,  5 Jan 2020 23:50:04 +0100, Luca Ceresoli wrote:
> Remove misplaced dot before colon.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/smbus-protocol.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
> index de7285de5e93..7350e4b2c2fa 100644
> --- a/Documentation/i2c/smbus-protocol.rst
> +++ b/Documentation/i2c/smbus-protocol.rst
> @@ -146,7 +146,7 @@ Implemented by i2c_smbus_write_word_data()
>  
>  This is the opposite of the Read Word operation. 16 bits
>  of data are 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
>  

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 02/26] docs: i2c: summary: extend introduction
  2020-01-20  9:27     ` Jean Delvare
@ 2020-01-20 21:54       ` Luca Ceresoli
  0 siblings, 0 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-20 21:54 UTC (permalink / raw)
  To: Jean Delvare
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

Hi Jean,

On 20/01/20 10:27, Jean Delvare wrote:
> On Sun,  5 Jan 2020 23:49:48 +0100, Luca Ceresoli wrote:
>> - state the "official" name (I²C, not I2C, according to the spec) at
>>    the beginning but keep using the more practical I2C elsewhere
>>  - mention some known different names
>>  - add link to the specification document
> 
> Indentation is inconsistent.

Weird, this looks OK in my git log and my inbox, wrong on patchwork.
Perhaps starting an e-mail with a space breaks something? I'll try to
avoid that in the future.

>> diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
>> index 3a24eac17375..b7d3e620155b 100644
>> --- a/Documentation/i2c/summary.rst
>> +++ b/Documentation/i2c/summary.rst
>> @@ -2,12 +2,18 @@
>>  I2C and SMBus
>>  =============
>>  
>> -I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
>> -slow two-wire protocol (variable speed, up to 400 kHz), with a high speed
>> -extension (3.4 MHz).  It provides an inexpensive bus for connecting many
>> -types of devices with infrequent or low bandwidth communications needs.
>> -I2C is widely used with embedded systems.  Some systems use variants that
>> -don't meet branding requirements, and so are not advertised as being I2C.
>> +I²C (pronounce: I squared C and written I2C in the kernel documentation) is
>> +a protocol developed by Philips. It is a slow two-wire protocol (variable
>> +speed, up to 400 kHz), with a high speed extension (3.4 MHz).  It provides
>> +an inexpensive bus for connecting many types of devices with infrequent or
>> +low bandwidth communications needs.  I2C is widely used with embedded
>> +systems.  Some systems use variants that don't meet branding requirements,
>> +and so are not advertised as being I2C but with different names, e.g. TWI
>> +(Two Wire Interface), IIC.
> 
> Maybe that's just me but "but with different names" sounds strange to
> me in the sentence construct. Maybe "but come under different names"
> instead?

What I mean is "...are not advertised as being I2C but [are advertised]
with different names". Looks equally clear to me, but since it has to be
clear to readers, I'll take your suggestion for v2.

Thanks for all the review work. I'm not going to reply to each e-mail
individually, but each of your suggestions will be taken in v2 unless I
reply differently.

-- 
Luca


^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 19/26] docs: i2c: smbus-protocol: improve I2C Block transactions description
  2020-01-05 22:50   ` [PATCH 19/26] docs: i2c: smbus-protocol: improve I2C Block transactions description Luca Ceresoli
@ 2020-01-21  9:16     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-21  9:16 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:50:05 +0100, Luca Ceresoli wrote:
> Clarify from the beginning what these transactions are, and specifically
> how they differ from the SMBus counterparts, i.e. the lack of a Count byte.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/smbus-protocol.rst | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
> index 7350e4b2c2fa..0edaf6069ac1 100644
> --- a/Documentation/i2c/smbus-protocol.rst
> +++ b/Documentation/i2c/smbus-protocol.rst
> @@ -282,9 +282,10 @@ This is implemented the following way in the Linux kernel:
>  I2C Block Transactions
>  ======================
>  
> -The following I2C block transactions are supported by the
> -SMBus layer and are described here for completeness.
> -They are *NOT* defined by the SMBus specification.
> +The following I2C block transactions are similar to the SMBus Block Read
> +and Write operations, except these do not have a Count byte. They are
> +supported by the SMBus layer and are described here for completeness, but
> +they are *NOT* defined by the SMBus specification.
>  
>  I2C block transactions do not limit the number of bytes transferred
>  but the SMBus layer places a limit of 32 bytes.

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 20/26] docs: i2c: instantiating-devices: fix internal hyperlink
  2020-01-05 22:50   ` [PATCH 20/26] docs: i2c: instantiating-devices: fix internal hyperlink Luca Ceresoli
@ 2020-01-21 10:07     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-21 10:07 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:50:06 +0100, Luca Ceresoli wrote:
> Use ReST syntax so that a proper hyperlink is generated.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/instantiating-devices.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
> index cf5d9828e823..5debaafef64d 100644
> --- a/Documentation/i2c/instantiating-devices.rst
> +++ b/Documentation/i2c/instantiating-devices.rst
> @@ -86,7 +86,7 @@ Method 1c: Declare the I2C devices via ACPI
>  -------------------------------------------
>  
>  ACPI can also describe I2C devices. There is special documentation for this
> -which is currently located at Documentation/firmware-guide/acpi/enumeration.rst.
> +which is currently located at :doc:`../firmware-guide/acpi/enumeration` .

You have an extra space before the dot, I don't think the ReST syntax
requires that?

>  
>  
>  Method 2: Instantiate the devices explicitly

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax
  2020-01-20 14:44     ` Jean Delvare
@ 2020-01-21 17:31       ` Luca Ceresoli
  2020-01-22 11:48         ` Jean Delvare
  2020-01-22 14:26         ` Jean Delvare
  0 siblings, 2 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-21 17:31 UTC (permalink / raw)
  To: Jean Delvare
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

Hi Jean,

On 20/01/20 15:44, Jean Delvare wrote:
> On Sun,  5 Jan 2020 23:50:01 +0100, Luca Ceresoli wrote:
>> Hyperlinks from function names are not generated in headings. Move them in
>> the plain text so they are rendered as clickable hyerlinks.
> 
> typo: hyperlinks

Ok.

>>
>> While there also remove an unneeded colon in a heading.
>>
>> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
>> ---
>>  Documentation/i2c/smbus-protocol.rst | 64 ++++++++++++++++++----------
>>  1 file changed, 42 insertions(+), 22 deletions(-)
>>
>> diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
>> index 10c4a989982c..997945e90419 100644
>> --- a/Documentation/i2c/smbus-protocol.rst
>> +++ b/Documentation/i2c/smbus-protocol.rst
>> @@ -62,8 +62,10 @@ This sends a single bit to the device, at the place of the Rd/Wr bit::
>>  Functionality flag: I2C_FUNC_SMBUS_QUICK
>>  
>>  
>> -SMBus Receive Byte:  i2c_smbus_read_byte()
>> -==========================================
>> +SMBus Receive Byte
>> +==================
>> +
>> +Implemented by i2c_smbus_read_byte()
> 
> In file i2c-protocol.rst, the wording used is:
> 
> This corresponds to i2c_transfer().
> 
> For consistency, can we settle for "Implemented by foo()" everywhere?

Good point. For v2 I added a new patch to use "Implemented by" also in
i2c-protocol.rst.

Thanks.

By extrapolation I guess you want to review the few remaining patches.
Correnct? In this case I'd wait for that before sending out v2.

-- 
Luca

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 21/26] docs: i2c: instantiating-devices: rearrange static instatiation
  2020-01-05 22:50   ` [PATCH 21/26] docs: i2c: instantiating-devices: rearrange static instatiation Luca Ceresoli
@ 2020-01-21 18:02     ` Jean Delvare
  2020-01-23  9:51       ` Luca Ceresoli
  0 siblings, 1 reply; 72+ messages in thread
From: Jean Delvare @ 2020-01-21 18:02 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:50:07 +0100, Luca Ceresoli wrote:
> Among the "static" instantiation methods the "board file" method is
> described first. Move it as last, since it is being replaced by the other
> methods.
> 
> Also fix subsubsection heading syntax and remove the "Method 1[abc]"
> prefix as the subsubsection structure clarifies the logical hierarchy.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/instantiating-devices.rst | 98 ++++++++++++---------
>  1 file changed, 54 insertions(+), 44 deletions(-)
> 
> diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
> index 5debaafef64d..cbcafb36b417 100644
> --- a/Documentation/i2c/instantiating-devices.rst
> +++ b/Documentation/i2c/instantiating-devices.rst
> @@ -9,54 +9,27 @@ reason, the kernel code must instantiate I2C devices explicitly. There are
>  several ways to achieve this, depending on the context and requirements.
>  
>  
> -Method 1a: Declare the I2C devices by bus number
> -------------------------------------------------
> +Method 1: Declare the I2C devices statically
> +--------------------------------------------
>  
>  This method is appropriate when the I2C bus is a system bus as is the case
> -for many embedded systems. On such systems, each I2C bus has a number
> -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().
> +for many embedded systems. On such systems, each I2C bus has a number which
> +is known in advance. It is thus possible to pre-declare the I2C devices
> +which live on this bus.
>  
> -Example (from omap2 h4)::
> +This information is provided to the kernel in a different way on different
> +architectures: device tree, ACPI or board files.
>  
> -  static struct i2c_board_info h4_i2c_board_info[] __initdata = {
> -	{
> -		I2C_BOARD_INFO("isp1301_omap", 0x2d),
> -		.irq		= OMAP_GPIO_IRQ(125),
> -	},
> -	{	/* EEPROM on mainboard */
> -		I2C_BOARD_INFO("24c01", 0x52),
> -		.platform_data	= &m24c01,
> -	},
> -	{	/* EEPROM on cpu card */
> -		I2C_BOARD_INFO("24c01", 0x57),
> -		.platform_data	= &m24c01,
> -	},
> -  };
> -
> -  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
> -question is registered, the I2C devices will be instantiated automatically
> -by i2c-core.
> +When the I2C bus in question is registered, the I2C devices will be
> +instantiated automatically by i2c-core. The devices will be automatically
> +unbound and destroyed when the I2C bus they sit on goes away (if ever).
>  
> -The devices will be automatically unbound and destroyed when the I2C bus
> -they sit on goes away (if ever.)
>  
> +Declare the I2C devices via devicetree
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  
> -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.
> +On platforms using devicetree the declaration of I2C devices is done in

I suggest adding a comma between "devicetree" and "the" to make the
sentence easier to read.

> +subnodes of the master controller.
>  
>  Example::
>  
> @@ -81,14 +54,51 @@ Here, two devices are attached to the bus using a speed of 100kHz. For
>  additional properties which might be needed to set up the device, please refer
>  to its devicetree documentation in Documentation/devicetree/bindings/.
>  
> -
> -Method 1c: Declare the I2C devices via ACPI
> --------------------------------------------
> +Declare the I2C devices via ACPI
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  
>  ACPI can also describe I2C devices. There is special documentation for this
>  which is currently located at :doc:`../firmware-guide/acpi/enumeration` .
>  
>  
> +Declare the I2C devices in board files
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In many embedded architectures devicetree has replaced the old hardware

Same here between "architectures" and "devicetree".

> +description based on board files, but the latter are still used in old
> +code. Instantiating I2C devices via board files is done with an array of
> +struct i2c_board_info which is registered by calling
> +i2c_register_board_info().
> +
> +Example (from omap2 h4)::
> +
> +  static struct i2c_board_info h4_i2c_board_info[] __initdata = {
> +	{
> +		I2C_BOARD_INFO("isp1301_omap", 0x2d),
> +		.irq		= OMAP_GPIO_IRQ(125),
> +	},
> +	{	/* EEPROM on mainboard */
> +		I2C_BOARD_INFO("24c01", 0x52),
> +		.platform_data	= &m24c01,
> +	},
> +	{	/* EEPROM on cpu card */
> +		I2C_BOARD_INFO("24c01", 0x57),
> +		.platform_data	= &m24c01,
> +	},
> +  };
> +
> +  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.
> +
> +
>  Method 2: Instantiate the devices explicitly
>  --------------------------------------------
>  


You have some inconsistency in your spacing between subsections, some
have 1 blank line before while some have 2. I think 1 is enough. At any
rate it should be consistent.

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 22/26] docs: i2c: instantiating-devices: use monospace for filenames
  2020-01-05 22:50   ` [PATCH 22/26] docs: i2c: instantiating-devices: use monospace for filenames Luca Ceresoli
@ 2020-01-22 10:08     ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-22 10:08 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:50:08 +0100, Luca Ceresoli wrote:
> Use a monospace (literal) formatting for better readability of filenames.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/instantiating-devices.rst | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
> index cbcafb36b417..f06d44c5b692 100644
> --- a/Documentation/i2c/instantiating-devices.rst
> +++ b/Documentation/i2c/instantiating-devices.rst
> @@ -224,15 +224,15 @@ In general, the kernel should know which I2C devices are connected and
>  what addresses they live at. However, in certain cases, it does not, so a
>  sysfs interface was added to let the user provide the information. This
>  interface is made of 2 attribute files which are created in every I2C bus
> -directory: new_device and delete_device. Both files are write only and you
> -must write the right parameters to them in order to properly instantiate,
> -respectively delete, an I2C device.
> +directory: ``new_device`` and ``delete_device``. Both files are write
> +only and you must write the right parameters to them in order to properly
> +instantiate, respectively delete, an I2C device.
>  
> -File new_device takes 2 parameters: the name of the I2C device (a string)
> -and the address of the I2C device (a number, typically expressed in
> -hexadecimal starting with 0x, but can also be expressed in decimal.)
> +File ``new_device`` takes 2 parameters: the name of the I2C device (a
> +string) and the address of the I2C device (a number, typically expressed
> +in hexadecimal starting with 0x, but can also be expressed in decimal.)
>  
> -File delete_device takes a single parameter: the address of the I2C
> +File ``delete_device`` takes a single parameter: the address of the I2C
>  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.

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 23/26] docs: i2c: old-module-parameters: fix internal hyperlink
  2020-01-05 22:50   ` [PATCH 23/26] docs: i2c: old-module-parameters: fix internal hyperlink Luca Ceresoli
@ 2020-01-22 10:16     ` Jean Delvare
  2020-01-23  9:50       ` Luca Ceresoli
  0 siblings, 1 reply; 72+ messages in thread
From: Jean Delvare @ 2020-01-22 10:16 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Sun,  5 Jan 2020 23:50:09 +0100, Luca Ceresoli wrote:
> Use ReST syntax so that a proper hyperlink is generated.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/old-module-parameters.rst | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
> index 78a6950e5763..0503d2f0b127 100644
> --- a/Documentation/i2c/old-module-parameters.rst
> +++ b/Documentation/i2c/old-module-parameters.rst
> @@ -12,8 +12,7 @@ address), "force" (to forcibly attach the driver to a given device) and
>  With the conversion of the I2C subsystem to the standard device driver
>  binding model, it became clear that these per-module parameters were no
>  longer needed, and that a centralized implementation was possible. The new,
> -sysfs-based interface is described in the documentation file
> -"instantiating-devices", section "Method 4: Instantiate from user-space".
> +sysfs-based interface is described in :doc:`instantiating-devices`.

I object to removing the reference to the section. I think this is
saving the reader some time so it is valuable.

>  
>  Below is a mapping from the old module parameters to the new interface.
>  

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 24/26] docs: i2c: old-module-parameters: clarify this is for obsolete kernels
  2020-01-06  7:46 ` [PATCH 24/26] docs: i2c: old-module-parameters: clarify this is for obsolete kernels Luca Ceresoli
@ 2020-01-22 11:18   ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-22 11:18 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Mon,  6 Jan 2020 08:46:39 +0100, Luca Ceresoli wrote:
> This section applies only to code for very old kernels. Avoid people
> reading this unnecessarily.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/old-module-parameters.rst | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
> index 0503d2f0b127..80fb117883fd 100644
> --- a/Documentation/i2c/old-module-parameters.rst
> +++ b/Documentation/i2c/old-module-parameters.rst
> @@ -2,6 +2,11 @@
>  I2C device driver binding control from user-space
>  =================================================
>  
> +.. NOTE::
> +   Note: this section is only relevant if you are handling some old code
> +   found in kernel 2.6. If you work with more recent kernels, you can
> +   safely skip this section.
> +
>  Up to kernel 2.6.32, many I2C drivers used helper macros provided by
>  <linux/i2c.h> which created standard module parameters to let the user
>  control how the driver would probe I2C buses and attach to devices. These

Reviewed-by: Jean Delvare <jdelvare@suse.de>


-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 25/26] docs: i2c: old-module-parameters: use monospace for filenames
  2020-01-06  7:46 ` [PATCH 25/26] docs: i2c: old-module-parameters: use monospace for filenames Luca Ceresoli
@ 2020-01-22 11:45   ` Jean Delvare
  0 siblings, 0 replies; 72+ messages in thread
From: Jean Delvare @ 2020-01-22 11:45 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Mon,  6 Jan 2020 08:46:54 +0100, Luca Ceresoli wrote:
> Use a monospace (literal) formatting for better readability of filenames.

This description and the subject are confusing. The strings you are
formatting are not filenames. They may be visible as sysfs attributes
and thus correspond to a filename, but primarily they are module
parameters and I2C client names.

> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/old-module-parameters.rst | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
> index 80fb117883fd..fdc470a5f999 100644
> --- a/Documentation/i2c/old-module-parameters.rst
> +++ b/Documentation/i2c/old-module-parameters.rst
> @@ -10,9 +10,9 @@ I2C device driver binding control from user-space
>  Up to kernel 2.6.32, many I2C drivers used helper macros provided by
>  <linux/i2c.h> which created standard module parameters to let the user
>  control how the driver would probe I2C buses and attach to devices. These
> -parameters were known as "probe" (to let the driver probe for an extra
> -address), "force" (to forcibly attach the driver to a given device) and
> -"ignore" (to prevent a driver from probing a given address).
> +parameters were known as ``probe`` (to let the driver probe for an extra
> +address), ``force`` (to forcibly attach the driver to a given device) and
> +``ignore`` (to prevent a driver from probing a given address).
>  
>  With the conversion of the I2C subsystem to the standard device driver
>  binding model, it became clear that these per-module parameters were no
> @@ -46,8 +46,8 @@ New method (sysfs interface)::
>    # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
>    # modprobe <driver>
>  
> -Of course, it is important to instantiate the "dummy" device before loading
> +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
>  other drivers from binding to it later on. If there is a real device at the
>  problematic address, and you want another driver to bind to it, then simply
> -pass the name of the device in question instead of "dummy".
> +pass the name of the device in question instead of ``dummy``.

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax
  2020-01-21 17:31       ` Luca Ceresoli
@ 2020-01-22 11:48         ` Jean Delvare
  2020-01-23  9:51           ` Luca Ceresoli
  2020-01-22 14:26         ` Jean Delvare
  1 sibling, 1 reply; 72+ messages in thread
From: Jean Delvare @ 2020-01-22 11:48 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Tue, 21 Jan 2020 18:31:23 +0100, Luca Ceresoli wrote:
> By extrapolation I guess you want to review the few remaining patches.
> Correnct? In this case I'd wait for that before sending out v2.

Yes, and I'm just done with it. Sorry it took so long but I was doing
it as a background task as my work schedule allowed.

One last thing you may want to fix: there's one occurrence of "stop
bit" left in Documentation/i2c/writing-clients.rst.

Thanks,
-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax
  2020-01-21 17:31       ` Luca Ceresoli
  2020-01-22 11:48         ` Jean Delvare
@ 2020-01-22 14:26         ` Jean Delvare
  2020-01-22 15:37           ` Wolfram Sang
  1 sibling, 1 reply; 72+ messages in thread
From: Jean Delvare @ 2020-01-22 14:26 UTC (permalink / raw)
  To: Luca Ceresoli
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

On Tue, 21 Jan 2020 18:31:23 +0100, Luca Ceresoli wrote:
> Good point. For v2 I added a new patch to use "Implemented by" also in
> i2c-protocol.rst.

BTW... I don't know how Wolfram feels about it, but I don't think
documentation changes need to be split to such fine-grained patches.
Chances that someone will want to cherry-pick specific changes are very
low in my opinion, so a large number of patches only means more
paperwork with little to no benefit. Some splitting is certainly nice
to make reviews easier, but only to a certain degree.

-- 
Jean Delvare
SUSE L3 Support

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax
  2020-01-22 14:26         ` Jean Delvare
@ 2020-01-22 15:37           ` Wolfram Sang
  2020-01-23  9:51             ` Luca Ceresoli
  0 siblings, 1 reply; 72+ messages in thread
From: Wolfram Sang @ 2020-01-22 15:37 UTC (permalink / raw)
  To: Jean Delvare
  Cc: Luca Ceresoli, linux-doc, linux-i2c, Peter Rosin, linux-kernel

[-- Attachment #1: Type: text/plain, Size: 674 bytes --]

On Wed, Jan 22, 2020 at 03:26:08PM +0100, Jean Delvare wrote:
> On Tue, 21 Jan 2020 18:31:23 +0100, Luca Ceresoli wrote:
> > Good point. For v2 I added a new patch to use "Implemented by" also in
> > i2c-protocol.rst.
> 
> BTW... I don't know how Wolfram feels about it, but I don't think
> documentation changes need to be split to such fine-grained patches.

I don't mind too much. I think for a first version, fine grained can
make review more easy. Maybe the second version could be less patches.
Yet for me, since patchwork can handle series of patches, the amount
doesn't matter too much. I am super happy that Luca did the work and you
did the review!


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 23/26] docs: i2c: old-module-parameters: fix internal hyperlink
  2020-01-22 10:16     ` Jean Delvare
@ 2020-01-23  9:50       ` Luca Ceresoli
  0 siblings, 0 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-23  9:50 UTC (permalink / raw)
  To: Jean Delvare
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

Hi Jean,

On 22/01/20 11:16, Jean Delvare wrote:
> On Sun,  5 Jan 2020 23:50:09 +0100, Luca Ceresoli wrote:
>> Use ReST syntax so that a proper hyperlink is generated.
>>
>> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
>> ---
>>  Documentation/i2c/old-module-parameters.rst | 3 +--
>>  1 file changed, 1 insertion(+), 2 deletions(-)
>>
>> diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
>> index 78a6950e5763..0503d2f0b127 100644
>> --- a/Documentation/i2c/old-module-parameters.rst
>> +++ b/Documentation/i2c/old-module-parameters.rst
>> @@ -12,8 +12,7 @@ address), "force" (to forcibly attach the driver to a given device) and
>>  With the conversion of the I2C subsystem to the standard device driver
>>  binding model, it became clear that these per-module parameters were no
>>  longer needed, and that a centralized implementation was possible. The new,
>> -sysfs-based interface is described in the documentation file
>> -"instantiating-devices", section "Method 4: Instantiate from user-space".
>> +sysfs-based interface is described in :doc:`instantiating-devices`.
> 
> I object to removing the reference to the section. I think this is
> saving the reader some time so it is valuable.

I agree, re-added in v2.

-- 
Luca

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax
  2020-01-22 11:48         ` Jean Delvare
@ 2020-01-23  9:51           ` Luca Ceresoli
  0 siblings, 0 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-23  9:51 UTC (permalink / raw)
  To: Jean Delvare
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

Hi Jean,

On 22/01/20 12:48, Jean Delvare wrote:
> On Tue, 21 Jan 2020 18:31:23 +0100, Luca Ceresoli wrote:
>> By extrapolation I guess you want to review the few remaining patches.
>> Correnct? In this case I'd wait for that before sending out v2.
> 
> Yes, and I'm just done with it. Sorry it took so long but I was doing
> it as a background task as my work schedule allowed.

No problem at all, it has been a background task for me as well! Thanks
again for the patient work. V2 will be out soon with the many precious
improvements you suggested.

> One last thing you may want to fix: there's one occurrence of "stop
> bit" left in Documentation/i2c/writing-clients.rst.

Thanks, added.

-- 
Luca

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 21/26] docs: i2c: instantiating-devices: rearrange static instatiation
  2020-01-21 18:02     ` Jean Delvare
@ 2020-01-23  9:51       ` Luca Ceresoli
  0 siblings, 0 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-23  9:51 UTC (permalink / raw)
  To: Jean Delvare
  Cc: linux-doc, linux-i2c, Wolfram Sang, Peter Rosin, linux-kernel

Hi Jean,

On 21/01/20 19:02, Jean Delvare wrote:
> On Sun,  5 Jan 2020 23:50:07 +0100, Luca Ceresoli wrote:
>> Among the "static" instantiation methods the "board file" method is
>> described first. Move it as last, since it is being replaced by the other
>> methods.
>>
>> Also fix subsubsection heading syntax and remove the "Method 1[abc]"
>> prefix as the subsubsection structure clarifies the logical hierarchy.
>>
>> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
>> ---
>>  Documentation/i2c/instantiating-devices.rst | 98 ++++++++++++---------
>>  1 file changed, 54 insertions(+), 44 deletions(-)
>>
>> diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
>> index 5debaafef64d..cbcafb36b417 100644
>> --- a/Documentation/i2c/instantiating-devices.rst
>> +++ b/Documentation/i2c/instantiating-devices.rst
>> @@ -9,54 +9,27 @@ reason, the kernel code must instantiate I2C devices explicitly. There are
>>  several ways to achieve this, depending on the context and requirements.
>>  
>>  
>> -Method 1a: Declare the I2C devices by bus number
>> -------------------------------------------------
>> +Method 1: Declare the I2C devices statically
>> +--------------------------------------------
>>  
>>  This method is appropriate when the I2C bus is a system bus as is the case
>> -for many embedded systems. On such systems, each I2C bus has a number
>> -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().
>> +for many embedded systems. On such systems, each I2C bus has a number which
>> +is known in advance. It is thus possible to pre-declare the I2C devices
>> +which live on this bus.
>>  
>> -Example (from omap2 h4)::
>> +This information is provided to the kernel in a different way on different
>> +architectures: device tree, ACPI or board files.
>>  
>> -  static struct i2c_board_info h4_i2c_board_info[] __initdata = {
>> -	{
>> -		I2C_BOARD_INFO("isp1301_omap", 0x2d),
>> -		.irq		= OMAP_GPIO_IRQ(125),
>> -	},
>> -	{	/* EEPROM on mainboard */
>> -		I2C_BOARD_INFO("24c01", 0x52),
>> -		.platform_data	= &m24c01,
>> -	},
>> -	{	/* EEPROM on cpu card */
>> -		I2C_BOARD_INFO("24c01", 0x57),
>> -		.platform_data	= &m24c01,
>> -	},
>> -  };
>> -
>> -  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
>> -question is registered, the I2C devices will be instantiated automatically
>> -by i2c-core.
>> +When the I2C bus in question is registered, the I2C devices will be
>> +instantiated automatically by i2c-core. The devices will be automatically
>> +unbound and destroyed when the I2C bus they sit on goes away (if ever).
>>  
>> -The devices will be automatically unbound and destroyed when the I2C bus
>> -they sit on goes away (if ever.)
>>  
>> +Declare the I2C devices via devicetree
>> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>  
>> -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.
>> +On platforms using devicetree the declaration of I2C devices is done in
> 
> I suggest adding a comma between "devicetree" and "the" to make the
> sentence easier to read.

OK.

>> +subnodes of the master controller.
>>  
>>  Example::
>>  
>> @@ -81,14 +54,51 @@ Here, two devices are attached to the bus using a speed of 100kHz. For
>>  additional properties which might be needed to set up the device, please refer
>>  to its devicetree documentation in Documentation/devicetree/bindings/.
>>  
>> -
>> -Method 1c: Declare the I2C devices via ACPI
>> --------------------------------------------
>> +Declare the I2C devices via ACPI
>> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>  
>>  ACPI can also describe I2C devices. There is special documentation for this
>>  which is currently located at :doc:`../firmware-guide/acpi/enumeration` .
>>  
>>  
>> +Declare the I2C devices in board files
>> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> +
>> +In many embedded architectures devicetree has replaced the old hardware
> 
> Same here between "architectures" and "devicetree".
> 
>> +description based on board files, but the latter are still used in old
>> +code. Instantiating I2C devices via board files is done with an array of
>> +struct i2c_board_info which is registered by calling
>> +i2c_register_board_info().
>> +
>> +Example (from omap2 h4)::
>> +
>> +  static struct i2c_board_info h4_i2c_board_info[] __initdata = {
>> +	{
>> +		I2C_BOARD_INFO("isp1301_omap", 0x2d),
>> +		.irq		= OMAP_GPIO_IRQ(125),
>> +	},
>> +	{	/* EEPROM on mainboard */
>> +		I2C_BOARD_INFO("24c01", 0x52),
>> +		.platform_data	= &m24c01,
>> +	},
>> +	{	/* EEPROM on cpu card */
>> +		I2C_BOARD_INFO("24c01", 0x57),
>> +		.platform_data	= &m24c01,
>> +	},
>> +  };
>> +
>> +  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.
>> +
>> +
>>  Method 2: Instantiate the devices explicitly
>>  --------------------------------------------
>>  
> 
> 
> You have some inconsistency in your spacing between subsections, some
> have 1 blank line before while some have 2. I think 1 is enough. At any
> rate it should be consistent.

I chose to have 2 lines as it is what was used (consistently) before my
changes.

-- 
Luca

^ permalink raw reply	[flat|nested] 72+ messages in thread

* Re: [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax
  2020-01-22 15:37           ` Wolfram Sang
@ 2020-01-23  9:51             ` Luca Ceresoli
  0 siblings, 0 replies; 72+ messages in thread
From: Luca Ceresoli @ 2020-01-23  9:51 UTC (permalink / raw)
  To: Wolfram Sang, Jean Delvare
  Cc: linux-doc, linux-i2c, Peter Rosin, linux-kernel

Hi,

On 22/01/20 16:37, Wolfram Sang wrote:
> On Wed, Jan 22, 2020 at 03:26:08PM +0100, Jean Delvare wrote:
>> On Tue, 21 Jan 2020 18:31:23 +0100, Luca Ceresoli wrote:
>>> Good point. For v2 I added a new patch to use "Implemented by" also in
>>> i2c-protocol.rst.
>>
>> BTW... I don't know how Wolfram feels about it, but I don't think
>> documentation changes need to be split to such fine-grained patches.
> 
> I don't mind too much. I think for a first version, fine grained can
> make review more easy. Maybe the second version could be less patches.
> Yet for me, since patchwork can handle series of patches, the amount
> doesn't matter too much. I am super happy that Luca did the work and you
> did the review!

I initially split this work in fine-grained patches for better reviewing
and also because some of the changes were not expected in the beginning:
while working at an improvement I noticed an unrelated one was needed.
But I agree the result is quite awkward. Coalescing some of them now
would be painful, so I'm sending v2 as is. But I'm tackling the
remaining sections later, and I'm going to do that work in a smaller
number of patches.

-- 
Luca

^ permalink raw reply	[flat|nested] 72+ messages in thread

end of thread, other threads:[~2020-01-23  9:51 UTC | newest]

Thread overview: 72+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-01-05 22:39 [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
2020-01-05 22:49   ` [PATCH 02/26] docs: i2c: summary: extend introduction Luca Ceresoli
2020-01-20  9:27     ` Jean Delvare
2020-01-20 21:54       ` Luca Ceresoli
2020-01-05 22:49   ` [PATCH 03/26] docs: i2c: summary: rewrite the "terminology" section Luca Ceresoli
2020-01-20 10:04     ` Jean Delvare
2020-01-05 22:49   ` [PATCH 04/26] docs: i2c: call it "I2C" consistently Luca Ceresoli
2020-01-07 10:33     ` Peter Rosin
2020-01-16  9:39     ` Jean Delvare
2020-01-05 22:49   ` [PATCH 05/26] docs: i2c: fix typo Luca Ceresoli
2020-01-07 10:33     ` Peter Rosin
2020-01-16  9:40     ` Jean Delvare
2020-01-05 22:49   ` [PATCH 06/26] docs: i2c: replace "I2C-transfer" -> "I2C transfer" consistently Luca Ceresoli
2020-01-07 10:34     ` Peter Rosin
2020-01-20 10:07     ` Jean Delvare
2020-01-05 22:49   ` [PATCH 07/26] docs: i2c: i2c-protocol: fix kernel-doc function syntax Luca Ceresoli
2020-01-20 10:51     ` Jean Delvare
2020-01-05 22:49   ` [PATCH 08/26] docs: i2c: i2c-protocol: properly name start and stop conditions Luca Ceresoli
2020-01-20 12:49     ` Jean Delvare
2020-01-05 22:49   ` [PATCH 09/26] docs: i2c: i2c-protocol: remove unneeded colons from table Luca Ceresoli
2020-01-20 13:38     ` Jean Delvare
2020-01-20 14:22       ` Jean Delvare
2020-01-05 22:49   ` [PATCH 10/26] docs: i2c: i2c-protocol: use proper names for ACK and NACK Luca Ceresoli
2020-01-20 13:50     ` Jean Delvare
2020-01-05 22:49   ` [PATCH 11/26] docs: i2c: smbus: fix link syntax Luca Ceresoli
2020-01-20 14:10     ` Jean Delvare
2020-01-05 22:49   ` [PATCH 12/26] docs: i2c: smbus-protocol: properly name start and stop conditions Luca Ceresoli
2020-01-20 14:16     ` Jean Delvare
2020-01-05 22:49   ` [PATCH 13/26] docs: i2c: smbus-protocol: remove unneeded colons from table Luca Ceresoli
2020-01-20 14:23     ` Jean Delvare
2020-01-05 22:50   ` [PATCH 14/26] docs: i2c: smbus-protocol: use proper names for ACK and NACK Luca Ceresoli
2020-01-20 14:26     ` Jean Delvare
2020-01-05 22:50   ` [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax Luca Ceresoli
2020-01-20 14:44     ` Jean Delvare
2020-01-21 17:31       ` Luca Ceresoli
2020-01-22 11:48         ` Jean Delvare
2020-01-23  9:51           ` Luca Ceresoli
2020-01-22 14:26         ` Jean Delvare
2020-01-22 15:37           ` Wolfram Sang
2020-01-23  9:51             ` Luca Ceresoli
2020-01-05 22:50   ` [PATCH 16/26] docs: i2c: smbus-protocol: fix " Luca Ceresoli
2020-01-20 14:51     ` Jean Delvare
2020-01-05 22:50   ` [PATCH 17/26] docs: i2c: i2c-protocol: fix typo Luca Ceresoli
2020-01-20 15:15     ` Jean Delvare
2020-01-05 22:50   ` [PATCH 18/26] docs: i2c: i2c-protocol: fix punctuation Luca Ceresoli
2020-01-20 15:16     ` Jean Delvare
2020-01-05 22:50   ` [PATCH 19/26] docs: i2c: smbus-protocol: improve I2C Block transactions description Luca Ceresoli
2020-01-21  9:16     ` Jean Delvare
2020-01-05 22:50   ` [PATCH 20/26] docs: i2c: instantiating-devices: fix internal hyperlink Luca Ceresoli
2020-01-21 10:07     ` Jean Delvare
2020-01-05 22:50   ` [PATCH 21/26] docs: i2c: instantiating-devices: rearrange static instatiation Luca Ceresoli
2020-01-21 18:02     ` Jean Delvare
2020-01-23  9:51       ` Luca Ceresoli
2020-01-05 22:50   ` [PATCH 22/26] docs: i2c: instantiating-devices: use monospace for filenames Luca Ceresoli
2020-01-22 10:08     ` Jean Delvare
2020-01-05 22:50   ` [PATCH 23/26] docs: i2c: old-module-parameters: fix internal hyperlink Luca Ceresoli
2020-01-22 10:16     ` Jean Delvare
2020-01-23  9:50       ` Luca Ceresoli
2020-01-20  9:08   ` [PATCH 01/26] docs: i2c: sort index logically Jean Delvare
2020-01-20  9:22     ` Luca Ceresoli
2020-01-20 13:56       ` Luca Ceresoli
2020-01-06  7:46 ` [PATCH 24/26] docs: i2c: old-module-parameters: clarify this is for obsolete kernels Luca Ceresoli
2020-01-22 11:18   ` Jean Delvare
2020-01-06  7:46 ` [PATCH 25/26] docs: i2c: old-module-parameters: use monospace for filenames Luca Ceresoli
2020-01-22 11:45   ` Jean Delvare
2020-01-06  7:49 ` [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer Luca Ceresoli
2020-01-07 10:36   ` Peter Rosin
2020-01-16  9:49   ` Jean Delvare
2020-01-16 10:38     ` Luca Ceresoli
2020-01-16 13:34       ` Peter Rosin
2020-01-06  8:03 ` [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).