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 and some cross-section changes.
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. 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.
v2 and v3 incorporate many improvements suggested by Jean Delvare and Peter
Rosin. A special thank you to Jean for his very patient and appreciated
review work of _all_ of the 26 patches. Thanks to his work the patches are
now 28. :) Patches 27 and 28 are the new ones.
Luca
Luca Ceresoli (28):
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-protocol: 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: smbus-protocol: fix typo
docs: i2c: smbus-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 sysfs attributes
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 instead of ""
docs: i2c: rename sections so the overall picture is clearer
docs: i2c: i2c-protocol: use same wording as smbus-protocol
docs: i2c: writing-clients: properly name the stop condition
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 | 58 +-
Documentation/i2c/instantiating-devices.rst | 115 +-
Documentation/i2c/old-module-parameters.rst | 31 +-
Documentation/i2c/slave-interface.rst | 4 +-
Documentation/i2c/smbus-protocol.rst | 107 +-
Documentation/i2c/summary.rst | 62 +-
Documentation/i2c/writing-clients.rst | 16 +-
12 files changed, 1653 insertions(+), 224 deletions(-)
create mode 100644 Documentation/i2c/i2c.svg
--
2.25.0
Hyperlinks from function names are not generated in headings. Move them in
the plain text so they are rendered as clickable hyperlinks.
While there also remove an unneeded colon in a heading.
Signed-off-by: Luca Ceresoli <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
Changes in v2:
- fix typo in commit message (Jean Delvare)
---
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.25.0
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 <[email protected]>
Acked-by: Peter Rosin <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
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.
---
Changes in v2:
- summary.rst: "Introductions" -> "Introduction" (suggested by Jean Delvare)
---
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 3b93cb88eebc..38e55829dee8 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 09f73a608e25..ce7230025b33 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -1,6 +1,6 @@
-=============
-I2C and SMBus
-=============
+=============================
+Introduction to I2C and SMBus
+=============================
I²C (pronounce: I squared C and written I2C in the kernel documentation) is
a protocol developed by Philips. It is a slow two-wire protocol (variable
diff --git a/Documentation/i2c/writing-clients.rst b/Documentation/i2c/writing-clients.rst
index 44d97b2c9a82..82aa33c964d3 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.25.0
The subject is plural, fix the verb.
Signed-off-by: Luca Ceresoli <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
Changes in v2:
- fix subject line (Jean Delvare)
---
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.25.0
Use a monospace (literal) formatting for better readability of sysfs
attributes and the "dummy" client name. This looks much more readable in
ReST-generated output.
Signed-off-by: Luca Ceresoli <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
Changes in v2:
- reword commit message to not mention filenames (Jean Delvare)
---
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 92a403d21a62..3b93cb88eebc 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
@@ -47,8 +47,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.25.0
In I2C there is no such thing as a "stop bit". Use the proper naming: "stop
condition".
Signed-off-by: Luca Ceresoli <[email protected]>
Reported-by: Jean Delvare <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
This patch is new in v2.
---
Documentation/i2c/writing-clients.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/i2c/writing-clients.rst b/Documentation/i2c/writing-clients.rst
index 82aa33c964d3..978cc8210bf3 100644
--- a/Documentation/i2c/writing-clients.rst
+++ b/Documentation/i2c/writing-clients.rst
@@ -357,9 +357,9 @@ read/written.
This sends a series of messages. Each message can be a read or write,
and they can be mixed in any way. The transactions are combined: no
-stop bit is sent between transaction. The i2c_msg structure contains
-for each message the client address, the number of bytes of the message
-and the message data itself.
+stop condition is issued between transaction. The i2c_msg structure
+contains for each message the client address, the number of bytes of the
+message and the message data itself.
You can read the file ``i2c-protocol`` for more information about the
actual I2C protocol.
--
2.25.0
Remove misplaced dot before colon.
Signed-off-by: Luca Ceresoli <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
Changes in v2:
- fix subject line (Jean Delvare)
---
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.25.0
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 <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
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.25.0
Use a monospace (literal) formatting for better readability of sysfs
attributes.
Signed-off-by: Luca Ceresoli <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
Changes in v2:
- reword commit message to not mention filenames
---
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 665bf00792ba..e558e0a77e0c 100644
--- a/Documentation/i2c/instantiating-devices.rst
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -225,15 +225,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.25.0
This section applies only to code for very old kernels. Avoid people
reading this unnecessarily.
Signed-off-by: Luca Ceresoli <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
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 1a18e2b0f593..92a403d21a62 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.25.0
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 <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
Changes in v2:
- add clarifying commas, make empty lines consistent (Jean Delvare)
---
Documentation/i2c/instantiating-devices.rst | 97 ++++++++++++---------
1 file changed, 54 insertions(+), 43 deletions(-)
diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
index e823c4ad4e7f..665bf00792ba 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::
@@ -82,13 +55,51 @@ 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.25.0
This clarifies these are functions (and would/will adds a hyperlink to the
function documentation if/when documented).
Signed-off-by: Luca Ceresoli <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
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.25.0
Use ReST syntax so that a proper hyperlink is generated.
Signed-off-by: Luca Ceresoli <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
Changes in v2:
- re-add the reference to the section (Jean Delvare)
---
Documentation/i2c/old-module-parameters.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
index 78a6950e5763..1a18e2b0f593 100644
--- a/Documentation/i2c/old-module-parameters.rst
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -12,8 +12,8 @@ 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`, section
+"Method 4: Instantiate from user-space".
Below is a mapping from the old module parameters to the new interface.
--
2.25.0
Use ReST syntax so that a proper hyperlink is generated.
Signed-off-by: Luca Ceresoli <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
Changes in v2:
- remove space before dot (Jean Delvare)
---
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 53244e2f0378..e823c4ad4e7f 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.25.0
In smbus-protocol.rst we use the text "Implemented by" for the same meaning
as "This corresponds to". Change everything to "Implemented by" for
coherency.
Signed-off-by: Luca Ceresoli <[email protected]>
Reported-by: Jean Delvare <[email protected]>
Reviewed-by: Jean Delvare <[email protected]>
---
This patch is new in v2.
---
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 6aafc3880bce..b2092f8f815d 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()::
+Implemented by 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()::
+Implemented by 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().
+Implemented by i2c_transfer().
They are just like the above transactions, but instead of a stop
condition P a start condition S is sent and the transaction continues.
--
2.25.0
On Wed, Jan 29, 2020 at 04:19:25PM +0100, Luca Ceresoli wrote:
>
> 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 and some cross-section changes.
>
> 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. 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.
>
> v2 and v3 incorporate many improvements suggested by Jean Delvare and Peter
> Rosin. A special thank you to Jean for his very patient and appreciated
> review work of _all_ of the 26 patches. Thanks to his work the patches are
> now 28. :) Patches 27 and 28 are the new ones.
I really want this in 5.6, so I applied them all to for-next. Other
fixes or improvements should be sent on top of this.
Thank you a *lot*, Luca! And Jean and Peter for the review.
Awesome work!