In case backend is not ready, ie: fail to wakeup or initialization, on
the returning of the I2C_SLAVE_WRITE_REQUESTED event, bus driver should
aware the backend status and might auto sending NACK on the next
incoming bytes for I2C master to retry.

Signed-off-by: Quan Nguyen <quan@os.amperecomputing.com>
Links:https://lore.kernel.org/linux-arm-kernel/556fa9e1-c54b-8370-4de7-c2d3ec7d6906@os.amperecomputing.com/


[wsa: made some wording more precise]
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Similar to commit fe99b819 ("docs: i2c: i2c-sysfs: fix hyperlinks"),
make other links in documentation consistent with the preferred way.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Tested-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

[JD: Update the subject
     One more typo fixed
     Drop the link to lm-sensors' README, it's irrelevant]

Signed-off-by: Bruce Duncan <bwduncan@gmail.com>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

The sequence of sections is a bit confusing here:

 * we list the mux locking scheme for existing drivers before introducing
   what mux locking schemes are
 * we list the caveats for each locking scheme (which are tricky) before
   the example of the simple use case

Restructure it entirely with the following logic:

 * Intro ("I2C muxes and complex topologies")
 * Locking
   - mux-locked
     - example
     - caveats
   - parent-locked
     - example
     - caveats
 * Complex examples
 * Mux type of existing device drivers

While there, also apply some other improvements:

 * convert the caveat list from a table (with only one column carrying
   content) to a bullet list.
 * add a small introductory text to bridge the gap from listing the use
   cases to telling about the hardware components to handle them and then
   the device drivers that implement those.
 * make empty lines usage more uniform

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Acked-by: Peter Rosin <peda@axentia.se>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

"Etc" here was never meant to be a heading, it became one while converting
to ReST.

It would be easy to just convert it to plain text, but rather remove it and
add an introductory text before the list that conveys the same meaning but
with a better reading flow.

Fixes: ccf988b6 ("docs: i2c: convert to ReST and add to driver-api bookset")
Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Acked-by: Peter Rosin <peda@axentia.se>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

"intension" should have probably been "intention", however "intent" seems
even better.

Reported-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Acked-by: Peter Rosin <peda@axentia.se>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

The value returned by an i2c driver's remove function is mostly ignored.
(Only an error message is printed if the value is non-zero that the
error is ignored.)

So change the prototype of the remove function to return no value. This
way driver authors are not tempted to assume that passing an error to
the upper layer is a good idea. All drivers are adapted accordingly.
There is no intended change of behaviour, all callbacks were prepared to
return 0 before.

Reviewed-by: Peter Senna Tschudin <peter.senna@gmail.com>
Reviewed-by: Jeremy Kerr <jk@codeconstruct.com.au>
Reviewed-by: Benjamin Mugnier <benjamin.mugnier@foss.st.com>
Reviewed-by: Javier Martinez Canillas <javierm@redhat.com>
Reviewed-by: Crt Mori <cmo@melexis.com>
Reviewed-by: Heikki Krogerus <heikki.krogerus@linux.intel.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: Marek Behún <kabel@kernel.org> # for leds-turris-omnia
Acked-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Reviewed-by: Petr Machata <petrm@nvidia.com> # for mlxsw
Reviewed-by: Maximilian Luz <luzmaximilian@gmail.com> # for surface3_power
Acked-by: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com> # for bmc150-accel-i2c + kxcjk-1013
Reviewed-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> # for media/* + staging/media/*
Acked-by: Miguel Ojeda <ojeda@kernel.org> # for auxdisplay/ht16k33 + auxdisplay/lcd2s
Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com> # for versaclock5
Reviewed-by: Ajay Gupta <ajayg@nvidia.com> # for ucsi_ccg
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> # for iio
Acked-by: Peter Rosin <peda@axentia.se> # for i2c-mux-*, max9860
Acked-by: Adrien Grassein <adrien.grassein@gmail.com> # for lontium-lt8912b
Reviewed-by: Jean Delvare <jdelvare@suse.de> # for hwmon, i2c-core and i2c/muxes
Acked-by: Corey Minyard <cminyard@mvista.com> # for IPMI
Reviewed-by: Vladimir Oltean <olteanv@gmail.com>
Acked-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Acked-by: Sebastian Reichel <sebastian.reichel@collabora.com> # for drivers/power
Acked-by: Krzysztof Hałasa <khalasa@piap.pl>
Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

dts files cannot be linked conveniently, thus replace them with literal
formatting.

The links to other rst pages are broken, fix them using the proper syntax.

Fixes: 31df7195 ("Documentation: i2c: Add doc for I2C sysfs")
Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Improve wording in a couple sentences.

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
[wsa: improved a little more]
Signed-off-by: Wolfram Sang <wsa@kernel.org>

These blocks can be nicely coloured via Sphinx.

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Use a more professional wording.

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

"Comm", "Count", "DataLow", "DataHigh" are not used in this section.

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

"as usual" does not mean much here, especially as these are introductory
sections and 10-bit addressing hasn't been introduced yet.

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

This sentence dates back to the pre-git era and it does not look very
professional... As there is no clear definition of "finished", and given
this page is already a pretty good overview, not to mention it is not the
kernel responsibility to document the protocol in detail, let's update the
text accordingly.

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Add SMBus PCI ID on Intel Meteor Lake-P.

Signed-off-by: Jarkko Nikula <jarkko.nikula@linux.intel.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Instead of documenting old-style probes, reference "simple probes" and
document the i2c_match_id function. This might help reduce the use of
two-argument probes in new code.

Signed-off-by: Stephen Kitt <steve@sk2.org>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Add SMBus PCI ID on Intel Raptor Lake PCH-S.

Signed-off-by: Jarkko Nikula <jarkko.nikula@linux.intel.com>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

The link to the I2C specification is broken. Although
"https://www.nxp.com" hosts Rev 7 (2021) of this specification, it is
behind a login-wall. Thus, an additional link has been added (which
doesn't require a login) and the NXP official docs link has been
updated.

Signed-off-by: Deep Majumder <deep@fastmail.in>
[wsa: minor updates to text and commit message]
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Sr is a repeated start, it is used in both I2C and SMBus protocols.

Provide its description and replace start ("S") conditions with repeated
start ("Sr") conditions when relevant. This allows the documentation to
match the SMBus specification available at [1].

[1] http://www.smbus.org/specs/SMBus_3_1_20180319.pdf



Signed-off-by: Miquel Raynal <miquel.raynal@bootlin.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Append i2c-sysfs to toctree in order to get rid of building warnings.

Fixes: 31df7195 ("Documentation: i2c: Add doc for I2C sysfs")
Signed-off-by: Hu Haowen <src.res@email.cn>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

This doc helps Linux users navigate through I2C sysfs and learn
the system I2C topology.

Signed-off-by: Alex Qiu <xqiu@google.com>
Reviewed-by: Guenter Roeck <linux@roeck-us.net>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

The :doc:`foo` tag is auto-generated via automarkup.py.
So, use the filename at the sources, instead of :doc:`foo`.

Acked-by: Wolfram Sang <wsa@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/569722e3f7d73d746c145ea78d2b4fbe5defee90.1623824363.git.mchehab+huawei@kernel.org


Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Devices offering SMBus block process calls are rare, so add it to the
testunit. This is also a good test case for testing proper
I2C_M_RECV_LEN flag handling of I2C bus masters emulating SMBus.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Fixes: a8335c64 ("i2c: add slave testunit driver")
Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Mention that new CMDs will be NACKed while the old one is still
on-going, that the I2C address parameter of READ_BYTES is 7 bit only,
and reword one paragraph to be more precise.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Add PCI ID of SMBus controller on Intel Alder Lake PCH-S

Signed-off-by: Jarkko Nikula <jarkko.nikula@linux.intel.com>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Here is an I2C slave backend driver which allows to test some uncommon
functionalities of the I2C and SMBus world. Usually, you need specific
devices to test e.g. SMBus Host Notify and such. With this driver you
just need the slave interface of another I2C controller.

This initial version has testcases for multi-master and SMBus Host
Notify. Already planned but not yet implemented are SMBus Alert and
messages with I2C_M_RECV_LEN.

Please read the documentation for further details.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

All the drivers have long since been upgraded, and all the important
information here is also included in the "Implementing I2C device
drivers" guide.

Signed-off-by: Stephen Kitt <steve@sk2.org>
Reviewed-by: Wolfram Sang <wsa@kernel.org>
Link: https://lore.kernel.org/r/20200806161456.8680-1-steve@sk2.org


Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add support for SMBus controller on Intel Emmitsburg PCH. This is the
same IP as used in Cannon Lake and derivatives.

Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
Signed-off-by: Jarkko Nikula <jarkko.nikula@linux.intel.com>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

And it has been for a while (since 2012 at least), only it was not
documented. Add it.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Drop doubled word "new".

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Wolfram Sang <wsa@kernel.org>
Cc: linux-i2c@vger.kernel.org
Link: https://lore.kernel.org/r/20200707180414.10467-10-rdunlap@infradead.org


Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add more details which have either been missing ever since or describe
recent additions.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
Reviewed-by: Luca Ceresoli <luca@lucaceresoli.net>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Just like all other I2C/SMBus commands, the start signal for the SMBus
Quick Command is S, not A.

Fixes: 1da177e4 ("Linux-2.6.12-rc2")
Signed-off-by: Daniel Schaefer <git@danielschaefer.me>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

When generating the PDF output, the Documentation/i2c dir
will generate an i2c.pdf. The same happens with i2c.svg:
it will also produce a file with the same name, at the same dir.

This causes errors when building the PDF output. So, rename the
image to i2c_bus.svg.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Wolfram Sang <wsa@the-dreams.de>
Link: https://lore.kernel.org/r/ecf3d51909ce46b3e84a1df4b36f07d76989e5da.1586881715.git.mchehab+huawei@kernel.org


Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Only few drivers use this call, so drivers and I2C core are converted at
once with this patch. By simply using i2c_new_client_device() instead of
i2c_new_device(), we easily can return an ERRPTR for this function as
well. To make out of tree users aware that something changed, the
function is renamed to i2c_new_smbus_alert_device().

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Reviewed-by: Luca Ceresoli <luca@lucaceresoli.net>
Signed-off-by: Wolfram Sang <wsa@the-dreams.de>

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

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
Reported-by: Jean Delvare <jdelvare@suse.de>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@the-dreams.de>

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 <luca@lucaceresoli.net>
Reported-by: Jean Delvare <jdelvare@suse.de>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@the-dreams.de>

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>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@the-dreams.de>

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 <luca@lucaceresoli.net>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@the-dreams.de>

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

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@the-dreams.de>