* [PATCH 0/5] Convert misc-devices, i2c, w1, spi and some markdown files to ReST
@ 2019-06-28 21:23 Mauro Carvalho Chehab
2019-06-28 21:23 ` [PATCH 1/5] docs: convert markdown documents " Mauro Carvalho Chehab
` (4 more replies)
0 siblings, 5 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 21:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Arnd Bergmann, Darren Hart, Hartmut Knaack,
Peter Meerwald-Stadler, linux-spi, Seth Heasley, Ajay Gupta,
Jim Cromie, Neil Horman, Rudolf Marek, Andreas Werner,
Rob Herring, Mark Rutland, Peter Rosin, Alexandre Belloni,
Mark Brown, linux-rtc, Wolfram Sang, linux-hwmon,
Vadim Pasternak, Peter Korsgaard, Eric Piel, Evgeniy Polyakov,
linux-iio, Greg Kroah-Hartman, platform-driver-x86,
Andy Shevchenko, Alessandro Zummo, Guenter Roeck, linux-i2c,
Michael Shych, Jonathan Cameron, Andrew Lunn, devicetree,
Jean Delvare, Lars-Peter Clausen
There are some files under Documentation/ that don't end with .txt but
as plain text files. If I did the math right, ~140 of such files make sense
to convert, IMO.
This series convert most of them. After this series, there will be around
30-40 files without any extension to be converted.
The results of this conversion (applied after my big conversion series)
can be seen at:
https://www.infradead.org/~mchehab/rst_conversion/
In order to make easier to merge, I'm placing one patch per subsystem,
plus a patch for the markdown->ReST conversion.
Mauro Carvalho Chehab (5):
docs: convert markdown documents to ReST
docs: misc-devices: convert files without extension to ReST
docs: i2c: convert to ReST and add to driver-api bookset
docs: w1: convert to ReST and add to the kAPI group of docs
docs: spi: convert to ReST and add it to the kABI bookset
Documentation/ABI/stable/sysfs-bus-w1 | 2 +-
.../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +-
.../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +-
Documentation/IPMB.txt | 2 +-
.../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +-
Documentation/devicetree/writing-schema.md | 130 ------------
Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++
...entication.md => ubifs-authentication.rst} | 70 ++++---
Documentation/hwmon/adm1021.rst | 2 +-
Documentation/hwmon/adm1275.rst | 2 +-
Documentation/hwmon/hih6130.rst | 2 +-
Documentation/hwmon/ibm-cffps.rst | 2 +-
Documentation/hwmon/lm25066.rst | 2 +-
Documentation/hwmon/max16064.rst | 2 +-
Documentation/hwmon/max16065.rst | 2 +-
Documentation/hwmon/max20751.rst | 2 +-
Documentation/hwmon/max34440.rst | 2 +-
Documentation/hwmon/max6650.rst | 2 +-
Documentation/hwmon/max8688.rst | 2 +-
Documentation/hwmon/menf21bmc.rst | 2 +-
Documentation/hwmon/pcf8591.rst | 2 +-
Documentation/hwmon/sht3x.rst | 2 +-
Documentation/hwmon/shtc1.rst | 2 +-
Documentation/hwmon/tmp103.rst | 2 +-
Documentation/hwmon/tps40422.rst | 2 +-
Documentation/hwmon/ucd9000.rst | 2 +-
Documentation/hwmon/ucd9200.rst | 2 +-
Documentation/hwmon/via686a.rst | 2 +-
Documentation/hwmon/zl6100.rst | 2 +-
.../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +-
.../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 +
.../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 63 +++---
Documentation/i2c/busses/i2c-amd-mp2 | 23 ---
Documentation/i2c/busses/i2c-amd-mp2.rst | 25 +++
.../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +-
.../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +-
.../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 +
.../i2c/busses/{i2c-i801 => i2c-i801.rst} | 31 ++-
.../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +-
.../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 +
.../busses/{i2c-nforce2 => i2c-nforce2.rst} | 23 ++-
.../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +-
.../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +-
Documentation/i2c/busses/i2c-parport | 178 ----------------
...2c-parport-light => i2c-parport-light.rst} | 2 +
Documentation/i2c/busses/i2c-parport.rst | 190 +++++++++++++++++
.../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +-
.../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 14 +-
.../busses/{i2c-sis5595 => i2c-sis5595.rst} | 18 +-
Documentation/i2c/busses/i2c-sis630 | 58 ------
Documentation/i2c/busses/i2c-sis630.rst | 64 ++++++
.../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 28 ++-
.../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +-
.../i2c/busses/{i2c-via => i2c-via.rst} | 20 +-
.../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +-
Documentation/i2c/busses/index.rst | 33 +++
.../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +-
.../i2c/{dev-interface => dev-interface.rst} | 94 +++++----
...-considerations => dma-considerations.rst} | 0
.../i2c/{fault-codes => fault-codes.rst} | 4 +
.../i2c/{functionality => functionality.rst} | 18 +-
...ult-injection => gpio-fault-injection.rst} | 12 +-
.../i2c/{i2c-protocol => i2c-protocol.rst} | 28 ++-
Documentation/i2c/{i2c-stub => i2c-stub.rst} | 19 +-
.../i2c/{i2c-topology => i2c-topology.rst} | 68 +++---
Documentation/i2c/index.rst | 38 ++++
...ting-devices => instantiating-devices.rst} | 45 ++--
.../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +--
...e-parameters => old-module-parameters.rst} | 27 ++-
...eprom-backend => slave-eeprom-backend.rst} | 3 +-
.../{slave-interface => slave-interface.rst} | 32 +--
.../{smbus-protocol => smbus-protocol.rst} | 74 ++++---
Documentation/i2c/{summary => summary.rst} | 4 +-
...en-bit-addresses => ten-bit-addresses.rst} | 5 +
...pgrading-clients => upgrading-clients.rst} | 194 +++++++++---------
.../{writing-clients => writing-clients.rst} | 94 +++++----
Documentation/index.rst | 3 +
.../misc-devices/{eeprom => eeprom.rst} | 43 ++--
.../{ics932s401 => ics932s401.rst} | 7 +-
Documentation/misc-devices/index.rst | 5 +
.../misc-devices/{isl29003 => isl29003.rst} | 15 +-
.../misc-devices/{lis3lv02d => lis3lv02d.rst} | 20 +-
.../misc-devices/{max6875 => max6875.rst} | 52 +++--
.../spi/{butterfly => butterfly.rst} | 44 ++--
Documentation/spi/index.rst | 23 +++
Documentation/spi/{pxa2xx => pxa2xx.rst} | 94 +++++----
.../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 +-
.../spi/{spi-sc18is602 => spi-sc18is602.rst} | 5 +-
.../spi/{spi-summary => spi-summary.rst} | 103 ++++++----
Documentation/spi/{spidev => spidev.rst} | 30 ++-
Documentation/w1/index.rst | 22 ++
.../w1/masters/{ds2482 => ds2482.rst} | 17 +-
.../w1/masters/{ds2490 => ds2490.rst} | 6 +-
Documentation/w1/masters/index.rst | 14 ++
Documentation/w1/masters/mxc-w1 | 12 --
Documentation/w1/masters/mxc-w1.rst | 17 ++
.../w1/masters/{omap-hdq => omap-hdq.rst} | 12 +-
.../w1/masters/{w1-gpio => w1-gpio.rst} | 21 +-
Documentation/w1/slaves/index.rst | 16 ++
.../w1/slaves/{w1_ds2406 => w1_ds2406.rst} | 2 +
.../w1/slaves/{w1_ds2413 => w1_ds2413.rst} | 9 +
Documentation/w1/slaves/w1_ds2423 | 47 -----
Documentation/w1/slaves/w1_ds2423.rst | 54 +++++
.../w1/slaves/{w1_ds2438 => w1_ds2438.rst} | 10 +-
.../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} | 5 +
.../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} | 15 +-
.../w1/slaves/{w1_therm => w1_therm.rst} | 11 +-
.../w1/{w1.generic => w1-generic.rst} | 88 ++++----
.../w1/{w1.netlink => w1-netlink.rst} | 83 ++++----
MAINTAINERS | 52 ++---
Next/merge.log | 6 +-
drivers/hwmon/atxp1.c | 2 +-
drivers/hwmon/smm665.c | 2 +-
drivers/i2c/Kconfig | 4 +-
drivers/i2c/busses/Kconfig | 2 +-
drivers/i2c/busses/i2c-i801.c | 2 +-
drivers/i2c/busses/i2c-taos-evm.c | 2 +-
drivers/i2c/i2c-core-base.c | 4 +-
drivers/iio/dummy/iio_simple_dummy.c | 4 +-
drivers/misc/isl29003.c | 2 +-
drivers/platform/x86/Kconfig | 2 +-
drivers/rtc/rtc-ds1374.c | 2 +-
drivers/spi/Kconfig | 2 +-
drivers/spi/spi-butterfly.c | 2 +-
drivers/spi/spi-lm70llp.c | 2 +-
include/linux/i2c.h | 2 +-
include/linux/platform_data/sc18is602.h | 2 +-
127 files changed, 1874 insertions(+), 1239 deletions(-)
delete mode 100644 Documentation/devicetree/writing-schema.md
create mode 100644 Documentation/devicetree/writing-schema.rst
rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
delete mode 100644 Documentation/i2c/busses/i2c-amd-mp2
create mode 100644 Documentation/i2c/busses/i2c-amd-mp2.rst
rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (68%)
rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
delete mode 100644 Documentation/i2c/busses/i2c-parport
rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (92%)
create mode 100644 Documentation/i2c/busses/i2c-parport.rst
rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
delete mode 100644 Documentation/i2c/busses/i2c-sis630
create mode 100644 Documentation/i2c/busses/i2c-sis630.rst
rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (75%)
rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (61%)
rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
create mode 100644 Documentation/i2c/busses/index.rst
rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
rename Documentation/i2c/{functionality => functionality.rst} (91%)
rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
create mode 100644 Documentation/i2c/index.rst
rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (84%)
rename Documentation/i2c/{summary => summary.rst} (96%)
rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (56%)
rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
rename Documentation/misc-devices/{eeprom => eeprom.rst} (76%)
rename Documentation/misc-devices/{ics932s401 => ics932s401.rst} (94%)
rename Documentation/misc-devices/{isl29003 => isl29003.rst} (77%)
rename Documentation/misc-devices/{lis3lv02d => lis3lv02d.rst} (90%)
rename Documentation/misc-devices/{max6875 => max6875.rst} (83%)
rename Documentation/spi/{butterfly => butterfly.rst} (71%)
create mode 100644 Documentation/spi/index.rst
rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
rename Documentation/spi/{spidev => spidev.rst} (90%)
create mode 100644 Documentation/w1/index.rst
rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
create mode 100644 Documentation/w1/masters/index.rst
delete mode 100644 Documentation/w1/masters/mxc-w1
create mode 100644 Documentation/w1/masters/mxc-w1.rst
rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
create mode 100644 Documentation/w1/slaves/index.rst
rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (97%)
rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
delete mode 100644 Documentation/w1/slaves/w1_ds2423
create mode 100644 Documentation/w1/slaves/w1_ds2423.rst
rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
rename Documentation/w1/{w1.netlink => w1-netlink.rst} (79%)
--
2.21.0
^ permalink raw reply [flat|nested] 14+ messages in thread
* [PATCH 1/5] docs: convert markdown documents to ReST
2019-06-28 21:23 [PATCH 0/5] Convert misc-devices, i2c, w1, spi and some markdown files to ReST Mauro Carvalho Chehab
@ 2019-06-28 21:23 ` Mauro Carvalho Chehab
2019-06-28 22:38 ` Rob Herring
2019-06-28 21:23 ` [PATCH 2/5] docs: misc-devices: convert files without extension " Mauro Carvalho Chehab
` (3 subsequent siblings)
4 siblings, 1 reply; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 21:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Rob Herring, Mark Rutland, devicetree
The documentation standard is ReST and not markdown.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/devicetree/writing-schema.md | 130 ---------------
Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++++++
...entication.md => ubifs-authentication.rst} | 70 +++++---
3 files changed, 197 insertions(+), 156 deletions(-)
delete mode 100644 Documentation/devicetree/writing-schema.md
create mode 100644 Documentation/devicetree/writing-schema.rst
rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.md
deleted file mode 100644
index dc032db36262..000000000000
--- a/Documentation/devicetree/writing-schema.md
+++ /dev/null
@@ -1,130 +0,0 @@
-# Writing DeviceTree Bindings in json-schema
-
-Devicetree bindings are written using json-schema vocabulary. Schema files are
-written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
-considered more human readable and has some advantages such as allowing
-comments (Prefixed with '#').
-
-## Schema Contents
-
-Each schema doc is a structured json-schema which is defined by a set of
-top-level properties. Generally, there is one binding defined per file. The
-top-level json-schema properties used are:
-
-- __$id__ - A json-schema unique identifier string. The string must be a valid
-URI typically containing the binding's filename and path. For DT schema, it must
-begin with "http://devicetree.org/schemas/". The URL is used in constructing
-references to other files specified in schema "$ref" properties. A $ref values
-with a leading '/' will have the hostname prepended. A $ref value a relative
-path or filename only will be prepended with the hostname and path components
-of the current schema file's '$id' value. A URL is used even for local files,
-but there may not actually be files present at those locations.
-
-- __$schema__ - Indicates the meta-schema the schema file adheres to.
-
-- __title__ - A one line description on the contents of the binding schema.
-
-- __maintainers__ - A DT specific property. Contains a list of email address(es)
-for maintainers of this binding.
-
-- __description__ - Optional. A multi-line text block containing any detailed
-information about this binding. It should contain things such as what the block
-or device does, standards the device conforms to, and links to datasheets for
-more information.
-
-- __select__ - Optional. A json-schema used to match nodes for applying the
-schema. By default without 'select', nodes are matched against their possible
-compatible string values or node name. Most bindings should not need select.
-
-- __allOf__ - Optional. A list of other schemas to include. This is used to
-include other schemas the binding conforms to. This may be schemas for a
-particular class of devices such as I2C or SPI controllers.
-
-- __properties__ - A set of sub-schema defining all the DT properties for the
-binding. The exact schema syntax depends on whether properties are known,
-common properties (e.g. 'interrupts') or are binding/vendor specific properties.
-
- A property can also define a child DT node with child properties defined
-under it.
-
- For more details on properties sections, see 'Property Schema' section.
-
-- __patternProperties__ - Optional. Similar to 'properties', but names are regex.
-
-- __required__ - A list of DT properties from the 'properties' section that
-must always be present.
-
-- __examples__ - Optional. A list of one or more DTS hunks implementing the
-binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
-
-Unless noted otherwise, all properties are required.
-
-## Property Schema
-
-The 'properties' section of the schema contains all the DT properties for a
-binding. Each property contains a set of constraints using json-schema
-vocabulary for that property. The properties schemas are what is used for
-validation of DT files.
-
-For common properties, only additional constraints not covered by the common
-binding schema need to be defined such as how many values are valid or what
-possible values are valid.
-
-Vendor specific properties will typically need more detailed schema. With the
-exception of boolean properties, they should have a reference to a type in
-schemas/types.yaml. A "description" property is always required.
-
-The Devicetree schemas don't exactly match the YAML encoded DT data produced by
-dtc. They are simplified to make them more compact and avoid a bunch of
-boilerplate. The tools process the schema files to produce the final schema for
-validation. There are currently 2 transformations the tools perform.
-
-The default for arrays in json-schema is they are variable sized and allow more
-entries than explicitly defined. This can be restricted by defining 'minItems',
-'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
-size is desired in most cases, so these properties are added based on the
-number of entries in an 'items' list.
-
-The YAML Devicetree format also makes all string values an array and scalar
-values a matrix (in order to define groupings) even when only a single value
-is present. Single entries in schemas are fixed up to match this encoding.
-
-## Testing
-
-### Dependencies
-
-The DT schema project must be installed in order to validate the DT schema
-binding documents and validate DTS files using the DT schema. The DT schema
-project can be installed with pip:
-
-`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master`
-
-dtc must also be built with YAML output support enabled. This requires that
-libyaml and its headers be installed on the host system.
-
-### Running checks
-
-The DT schema binding documents must be validated using the meta-schema (the
-schema for the schema) to ensure they are both valid json-schema and valid
-binding schema. All of the DT binding documents can be validated using the
-`dt_binding_check` target:
-
-`make dt_binding_check`
-
-In order to perform validation of DT source files, use the `dtbs_check` target:
-
-`make dtbs_check`
-
-This will first run the `dt_binding_check` which generates the processed schema.
-
-It is also possible to run checks with a single schema file by setting the
-'DT_SCHEMA_FILES' variable to a specific schema file.
-
-`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml`
-
-
-## json-schema Resources
-
-[JSON-Schema Specifications](http://json-schema.org/)
-
-[Using JSON Schema Book](http://usingjsonschema.com/)
diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
new file mode 100644
index 000000000000..8f71d1e2ac52
--- /dev/null
+++ b/Documentation/devicetree/writing-schema.rst
@@ -0,0 +1,153 @@
+:orphan:
+
+Writing DeviceTree Bindings in json-schema
+==========================================
+
+Devicetree bindings are written using json-schema vocabulary. Schema files are
+written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
+considered more human readable and has some advantages such as allowing
+comments (Prefixed with '#').
+
+Schema Contents
+---------------
+
+Each schema doc is a structured json-schema which is defined by a set of
+top-level properties. Generally, there is one binding defined per file. The
+top-level json-schema properties used are:
+
+$id
+ A json-schema unique identifier string. The string must be a valid
+ URI typically containing the binding's filename and path. For DT schema, it must
+ begin with "http://devicetree.org/schemas/". The URL is used in constructing
+ references to other files specified in schema "$ref" properties. A $ref values
+ with a leading '/' will have the hostname prepended. A $ref value a relative
+ path or filename only will be prepended with the hostname and path components
+ of the current schema file's '$id' value. A URL is used even for local files,
+ but there may not actually be files present at those locations.
+
+$schema
+ Indicates the meta-schema the schema file adheres to.
+
+title
+ A one line description on the contents of the binding schema.
+
+maintainers
+ A DT specific property. Contains a list of email address(es)
+ for maintainers of this binding.
+
+description
+ Optional. A multi-line text block containing any detailed
+ information about this binding. It should contain things such as what the block
+ or device does, standards the device conforms to, and links to datasheets for
+ more information.
+
+select
+ Optional. A json-schema used to match nodes for applying the
+ schema. By default without 'select', nodes are matched against their possible
+ compatible string values or node name. Most bindings should not need select.
+
+ allOf
+ Optional. A list of other schemas to include. This is used to
+ include other schemas the binding conforms to. This may be schemas for a
+ particular class of devices such as I2C or SPI controllers.
+
+ properties
+ A set of sub-schema defining all the DT properties for the
+ binding. The exact schema syntax depends on whether properties are known,
+ common properties (e.g. 'interrupts') or are binding/vendor specific properties.
+
+A property can also define a child DT node with child properties defined
+under it.
+
+For more details on properties sections, see 'Property Schema' section.
+
+patternProperties
+ Optional. Similar to 'properties', but names are regex.
+
+required
+ A list of DT properties from the 'properties' section that
+ must always be present.
+
+examples
+ Optional. A list of one or more DTS hunks implementing the
+ binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
+
+Unless noted otherwise, all properties are required.
+
+Property Schema
+---------------
+
+The 'properties' section of the schema contains all the DT properties for a
+binding. Each property contains a set of constraints using json-schema
+vocabulary for that property. The properties schemas are what is used for
+validation of DT files.
+
+For common properties, only additional constraints not covered by the common
+binding schema need to be defined such as how many values are valid or what
+possible values are valid.
+
+Vendor specific properties will typically need more detailed schema. With the
+exception of boolean properties, they should have a reference to a type in
+schemas/types.yaml. A "description" property is always required.
+
+The Devicetree schemas don't exactly match the YAML encoded DT data produced by
+dtc. They are simplified to make them more compact and avoid a bunch of
+boilerplate. The tools process the schema files to produce the final schema for
+validation. There are currently 2 transformations the tools perform.
+
+The default for arrays in json-schema is they are variable sized and allow more
+entries than explicitly defined. This can be restricted by defining 'minItems',
+'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
+size is desired in most cases, so these properties are added based on the
+number of entries in an 'items' list.
+
+The YAML Devicetree format also makes all string values an array and scalar
+values a matrix (in order to define groupings) even when only a single value
+is present. Single entries in schemas are fixed up to match this encoding.
+
+Testing
+-------
+
+Dependencies
+~~~~~~~~~~~~
+
+The DT schema project must be installed in order to validate the DT schema
+binding documents and validate DTS files using the DT schema. The DT schema
+project can be installed with pip::
+
+ pip3 install git+https://github.com/devicetree-org/dt-schema.git@master
+
+dtc must also be built with YAML output support enabled. This requires that
+libyaml and its headers be installed on the host system.
+
+Running checks
+~~~~~~~~~~~~~~
+
+The DT schema binding documents must be validated using the meta-schema (the
+schema for the schema) to ensure they are both valid json-schema and valid
+binding schema. All of the DT binding documents can be validated using the
+``dt_binding_check`` target::
+
+ make dt_binding_check
+
+In order to perform validation of DT source files, use the `dtbs_check` target::
+
+ make dtbs_check
+
+This will first run the `dt_binding_check` which generates the processed schema.
+
+It is also possible to run checks with a single schema file by setting the
+``DT_SCHEMA_FILES`` variable to a specific schema file.
+
+::
+
+ make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
+
+
+json-schema Resources
+---------------------
+
+
+`JSON-Schema Specifications <http://json-schema.org/>`_
+
+`Using JSON Schema Book <http://usingjsonschema.com/>`_
diff --git a/Documentation/filesystems/ubifs-authentication.md b/Documentation/filesystems/ubifs-authentication.rst
similarity index 95%
rename from Documentation/filesystems/ubifs-authentication.md
rename to Documentation/filesystems/ubifs-authentication.rst
index 23e698167141..6a9584f6ff46 100644
--- a/Documentation/filesystems/ubifs-authentication.md
+++ b/Documentation/filesystems/ubifs-authentication.rst
@@ -1,8 +1,11 @@
-% UBIFS Authentication
-% sigma star gmbh
-% 2018
+:orphan:
-# Introduction
+.. UBIFS Authentication
+.. sigma star gmbh
+.. 2018
+
+Introduction
+============
UBIFS utilizes the fscrypt framework to provide confidentiality for file
contents and file names. This prevents attacks where an attacker is able to
@@ -33,7 +36,8 @@ existing features like key derivation can be utilized. It should however also
be possible to use UBIFS authentication without using encryption.
-## MTD, UBI & UBIFS
+MTD, UBI & UBIFS
+----------------
On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform
interface to access raw flash devices. One of the more prominent subsystems that
@@ -47,7 +51,7 @@ UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear
leveling and some flash specifics are left to UBI, while UBIFS focuses on
scalability, performance and recoverability.
-
+::
+------------+ +*******+ +-----------+ +-----+
| | * UBIFS * | UBI-BLOCK | | ... |
@@ -84,7 +88,8 @@ persisted onto the flash directly. More details on UBIFS can also be found in
[UBIFS-WP].
-### UBIFS Index & Tree Node Cache
+UBIFS Index & Tree Node Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types
of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file
@@ -118,17 +123,18 @@ on-flash filesystem structures like the index. On every commit, the TNC nodes
marked as dirty are written to the flash to update the persisted index.
-### Journal
+Journal
+~~~~~~~
To avoid wearing out the flash, the index is only persisted (*commited*) when
-certain conditions are met (eg. `fsync(2)`). The journal is used to record
+certain conditions are met (eg. ``fsync(2)``). The journal is used to record
any changes (in form of inode nodes, data nodes etc.) between commits
of the index. During mount, the journal is read from the flash and replayed
onto the TNC (which will be created on-demand from the on-flash index).
UBIFS reserves a bunch of LEBs just for the journal called *log area*. The
amount of log area LEBs is configured on filesystem creation (using
-`mkfs.ubifs`) and stored in the superblock node. The log area contains only
+``mkfs.ubifs``) and stored in the superblock node. The log area contains only
two types of nodes: *reference nodes* and *commit start nodes*. A commit start
node is written whenever an index commit is performed. Reference nodes are
written on every journal update. Each reference node points to the position of
@@ -152,6 +158,7 @@ done for the last referenced LEB of the journal. Only this can become corrupt
because of a power cut. If the recovery fails, UBIFS will not mount. An error
for every other LEB will directly cause UBIFS to fail the mount operation.
+::
| ---- LOG AREA ---- | ---------- MAIN AREA ------------ |
@@ -172,10 +179,11 @@ for every other LEB will directly cause UBIFS to fail the mount operation.
containing their buds
-### LEB Property Tree/Table
+LEB Property Tree/Table
+~~~~~~~~~~~~~~~~~~~~~~~
The LEB property tree is used to store per-LEB information. This includes the
-LEB type and amount of free and *dirty* (old, obsolete content) space [1] on
+LEB type and amount of free and *dirty* (old, obsolete content) space [1]_ on
the LEB. The type is important, because UBIFS never mixes index nodes with data
nodes on a single LEB and thus each LEB has a specific purpose. This again is
useful for free space calculations. See [UBIFS-WP] for more details.
@@ -185,19 +193,21 @@ index. Due to its smaller size it is always written as one chunk on every
commit. Thus, saving the LPT is an atomic operation.
-[1] Since LEBs can only be appended and never overwritten, there is a
-difference between free space ie. the remaining space left on the LEB to be
-written to without erasing it and previously written content that is obsolete
-but can't be overwritten without erasing the full LEB.
+.. [1] Since LEBs can only be appended and never overwritten, there is a
+ difference between free space ie. the remaining space left on the LEB to be
+ written to without erasing it and previously written content that is obsolete
+ but can't be overwritten without erasing the full LEB.
-# UBIFS Authentication
+UBIFS Authentication
+====================
This chapter introduces UBIFS authentication which enables UBIFS to verify
the authenticity and integrity of metadata and file contents stored on flash.
-## Threat Model
+Threat Model
+------------
UBIFS authentication enables detection of offline data modification. While it
does not prevent it, it enables (trusted) code to check the integrity and
@@ -224,7 +234,8 @@ Additional measures like secure boot and trusted boot have to be taken to
ensure that only trusted code is executed on a device.
-## Authentication
+Authentication
+--------------
To be able to fully trust data read from flash, all UBIFS data structures
stored on flash are authenticated. That is:
@@ -236,7 +247,8 @@ stored on flash are authenticated. That is:
- The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting
-### Index Authentication
+Index Authentication
+~~~~~~~~~~~~~~~~~~~~
Through UBIFS' concept of a wandering tree, it already takes care of only
updating and persisting changed parts from leaf node up to the root node
@@ -260,6 +272,7 @@ include a hash. All other types of nodes will remain unchanged. This reduces
the storage overhead which is precious for users of UBIFS (ie. embedded
devices).
+::
+---------------+
| Master Node |
@@ -303,7 +316,8 @@ hashes to index nodes does not change this since each hash will be persisted
atomically together with its respective node.
-### Journal Authentication
+Journal Authentication
+~~~~~~~~~~~~~~~~~~~~~~
The journal is authenticated too. Since the journal is continuously written
it is necessary to also add authentication information frequently to the
@@ -316,7 +330,7 @@ of the hash chain. That way a journal can be authenticated up to the last
authentication node. The tail of the journal which may not have a authentication
node cannot be authenticated and is skipped during journal replay.
-We get this picture for journal authentication:
+We get this picture for journal authentication::
,,,,,,,,
,......,...........................................
@@ -352,7 +366,8 @@ the superblock struct. The superblock node is stored in LEB 0 and is only
modified on feature flag or similar changes, but never on file changes.
-### LPT Authentication
+LPT Authentication
+~~~~~~~~~~~~~~~~~~
The location of the LPT root node on the flash is stored in the UBIFS master
node. Since the LPT is written and read atomically on every commit, there is
@@ -363,7 +378,8 @@ be verified by verifying the authenticity of the master node and comparing the
LTP hash stored there with the hash computed from the read on-flash LPT.
-## Key Management
+Key Management
+--------------
For simplicity, UBIFS authentication uses a single key to compute the HMACs
of superblock, master, commit start and reference nodes. This key has to be
@@ -399,7 +415,8 @@ approach is similar to the approach proposed for fscrypt encryption policy v2
[FSCRYPT-POLICY2].
-# Future Extensions
+Future Extensions
+=================
In certain cases where a vendor wants to provide an authenticated filesystem
image to customers, it should be possible to do so without sharing the secret
@@ -411,7 +428,8 @@ to the way the IMA/EVM subsystem deals with such situations. The HMAC key
will then have to be provided beforehand in the normal way.
-# References
+References
+==========
[CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html
--
2.21.0
^ permalink raw reply related [flat|nested] 14+ messages in thread
* [PATCH 2/5] docs: misc-devices: convert files without extension to ReST
2019-06-28 21:23 [PATCH 0/5] Convert misc-devices, i2c, w1, spi and some markdown files to ReST Mauro Carvalho Chehab
2019-06-28 21:23 ` [PATCH 1/5] docs: convert markdown documents " Mauro Carvalho Chehab
@ 2019-06-28 21:23 ` Mauro Carvalho Chehab
2019-06-28 21:23 ` [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset Mauro Carvalho Chehab
` (2 subsequent siblings)
4 siblings, 0 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 21:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jean Delvare, Eric Piel, Arnd Bergmann,
Greg Kroah-Hartman, Darren Hart, Andy Shevchenko,
platform-driver-x86
Those files are also text files. Convert them to ReST and add
to the misc-files index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../misc-devices/{eeprom => eeprom.rst} | 43 +++++++++------
.../{ics932s401 => ics932s401.rst} | 7 ++-
Documentation/misc-devices/index.rst | 5 ++
.../misc-devices/{isl29003 => isl29003.rst} | 15 +++++-
.../misc-devices/{lis3lv02d => lis3lv02d.rst} | 20 ++++---
.../misc-devices/{max6875 => max6875.rst} | 52 ++++++++++++++-----
MAINTAINERS | 4 +-
drivers/misc/isl29003.c | 2 +-
drivers/platform/x86/Kconfig | 2 +-
9 files changed, 108 insertions(+), 42 deletions(-)
rename Documentation/misc-devices/{eeprom => eeprom.rst} (76%)
rename Documentation/misc-devices/{ics932s401 => ics932s401.rst} (94%)
rename Documentation/misc-devices/{isl29003 => isl29003.rst} (77%)
rename Documentation/misc-devices/{lis3lv02d => lis3lv02d.rst} (90%)
rename Documentation/misc-devices/{max6875 => max6875.rst} (83%)
diff --git a/Documentation/misc-devices/eeprom b/Documentation/misc-devices/eeprom.rst
similarity index 76%
rename from Documentation/misc-devices/eeprom
rename to Documentation/misc-devices/eeprom.rst
index ba692011f221..008249675ccc 100644
--- a/Documentation/misc-devices/eeprom
+++ b/Documentation/misc-devices/eeprom.rst
@@ -1,11 +1,17 @@
+====================
Kernel driver eeprom
====================
Supported chips:
+
* Any EEPROM chip in the designated address range
+
Prefix: 'eeprom'
+
Addresses scanned: I2C 0x50 - 0x57
+
Datasheets: Publicly available from:
+
Atmel (www.atmel.com),
Catalyst (www.catsemi.com),
Fairchild (www.fairchildsemi.com),
@@ -16,7 +22,9 @@ Supported chips:
Xicor (www.xicor.com),
and others.
- Chip Size (bits) Address
+ ========= ============= ============================================
+ Chip Size (bits) Address
+ ========= ============= ============================================
24C01 1K 0x50 (shadows at 0x51 - 0x57)
24C01A 1K 0x50 - 0x57 (Typical device on DIMMs)
24C02 2K 0x50 - 0x57
@@ -24,7 +32,7 @@ Supported chips:
(additional data at 0x51, 0x53, 0x55, 0x57)
24C08 8K 0x50, 0x54 (additional data at 0x51, 0x52,
0x53, 0x55, 0x56, 0x57)
- 24C16 16K 0x50 (additional data at 0x51 - 0x57)
+ 24C16 16K 0x50 (additional data at 0x51 - 0x57)
Sony 2K 0x57
Atmel 34C02B 2K 0x50 - 0x57, SW write protect at 0x30-37
@@ -33,14 +41,15 @@ Supported chips:
Fairchild 34W02 2K 0x50 - 0x57, SW write protect at 0x30-37
Microchip 24AA52 2K 0x50 - 0x57, SW write protect at 0x30-37
ST M34C02 2K 0x50 - 0x57, SW write protect at 0x30-37
+ ========= ============= ============================================
Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>,
- Jean Delvare <jdelvare@suse.de>,
- Greg Kroah-Hartman <greg@kroah.com>,
- IBM Corp.
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Philip Edelbrock <phil@netroedge.com>,
+ - Jean Delvare <jdelvare@suse.de>,
+ - Greg Kroah-Hartman <greg@kroah.com>,
+ - IBM Corp.
Description
-----------
@@ -74,23 +83,25 @@ this address will write protect the memory array permanently, and the
device will no longer respond at the 0x30-37 address. The eeprom driver
does not support this register.
-Lacking functionality:
+Lacking functionality
+---------------------
* Full support for larger devices (24C04, 24C08, 24C16). These are not
-typically found on a PC. These devices will appear as separate devices at
-multiple addresses.
+ typically found on a PC. These devices will appear as separate devices at
+ multiple addresses.
* Support for really large devices (24C32, 24C64, 24C128, 24C256, 24C512).
-These devices require two-byte address fields and are not supported.
+ These devices require two-byte address fields and are not supported.
* Enable Writing. Again, no technical reason why not, but making it easy
-to change the contents of the EEPROMs (on DIMMs anyway) also makes it easy
-to disable the DIMMs (potentially preventing the computer from booting)
-until the values are restored somehow.
+ to change the contents of the EEPROMs (on DIMMs anyway) also makes it easy
+ to disable the DIMMs (potentially preventing the computer from booting)
+ until the values are restored somehow.
-Use:
+Use
+---
After inserting the module (and any other required SMBus/i2c modules), you
-should have some EEPROM directories in /sys/bus/i2c/devices/* of names such
+should have some EEPROM directories in ``/sys/bus/i2c/devices/*`` of names such
as "0-0050". Inside each of these is a series of files, the eeprom file
contains the binary data from EEPROM.
diff --git a/Documentation/misc-devices/ics932s401 b/Documentation/misc-devices/ics932s401.rst
similarity index 94%
rename from Documentation/misc-devices/ics932s401
rename to Documentation/misc-devices/ics932s401.rst
index bdac67ff6e3f..613ee54a9c21 100644
--- a/Documentation/misc-devices/ics932s401
+++ b/Documentation/misc-devices/ics932s401.rst
@@ -1,10 +1,15 @@
+========================
Kernel driver ics932s401
-======================
+========================
Supported chips:
+
* IDT ICS932S401
+
Prefix: 'ics932s401'
+
Addresses scanned: I2C 0x69
+
Datasheet: Publicly available at the IDT website
Author: Darrick J. Wong
diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst
index dfd1f45a3127..a57f92dfe49a 100644
--- a/Documentation/misc-devices/index.rst
+++ b/Documentation/misc-devices/index.rst
@@ -14,4 +14,9 @@ fit into other categories.
.. toctree::
:maxdepth: 2
+ eeprom
ibmvmc
+ ics932s401
+ isl29003
+ lis3lv02d
+ max6875
diff --git a/Documentation/misc-devices/isl29003 b/Documentation/misc-devices/isl29003.rst
similarity index 77%
rename from Documentation/misc-devices/isl29003
rename to Documentation/misc-devices/isl29003.rst
index 80b952fd32ff..0cc38aed6c00 100644
--- a/Documentation/misc-devices/isl29003
+++ b/Documentation/misc-devices/isl29003.rst
@@ -1,10 +1,15 @@
+======================
Kernel driver isl29003
-=====================
+======================
Supported chips:
+
* Intersil ISL29003
+
Prefix: 'isl29003'
+
Addresses scanned: none
+
Datasheet:
http://www.intersil.com/data/fn/fn7464.pdf
@@ -37,25 +42,33 @@ Sysfs entries
-------------
range:
+ == ===========================
0: 0 lux to 1000 lux (default)
1: 0 lux to 4000 lux
2: 0 lux to 16,000 lux
3: 0 lux to 64,000 lux
+ == ===========================
resolution:
+ == =====================
0: 2^16 cycles (default)
1: 2^12 cycles
2: 2^8 cycles
3: 2^4 cycles
+ == =====================
mode:
+ == =================================================
0: diode1's current (unsigned 16bit) (default)
1: diode1's current (unsigned 16bit)
2: difference between diodes (l1 - l2, signed 15bit)
+ == =================================================
power_state:
+ == =================================================
0: device is disabled (default)
1: device is enabled
+ == =================================================
lux (read only):
returns the value from the last sensor reading
diff --git a/Documentation/misc-devices/lis3lv02d b/Documentation/misc-devices/lis3lv02d.rst
similarity index 90%
rename from Documentation/misc-devices/lis3lv02d
rename to Documentation/misc-devices/lis3lv02d.rst
index f89960a0ff95..959bd2b822cf 100644
--- a/Documentation/misc-devices/lis3lv02d
+++ b/Documentation/misc-devices/lis3lv02d.rst
@@ -1,3 +1,4 @@
+=======================
Kernel driver lis3lv02d
=======================
@@ -8,8 +9,8 @@ Supported chips:
LIS331DLH (16 bits)
Authors:
- Yan Burman <burman.yan@gmail.com>
- Eric Piel <eric.piel@tremplin-utc.net>
+ - Yan Burman <burman.yan@gmail.com>
+ - Eric Piel <eric.piel@tremplin-utc.net>
Description
@@ -25,11 +26,15 @@ neverball). The accelerometer data is readable via
to mg values (1/1000th of earth gravity).
Sysfs attributes under /sys/devices/platform/lis3lv02d/:
-position - 3D position that the accelerometer reports. Format: "(x,y,z)"
-rate - read reports the sampling rate of the accelerometer device in HZ.
+
+position
+ - 3D position that the accelerometer reports. Format: "(x,y,z)"
+rate
+ - read reports the sampling rate of the accelerometer device in HZ.
write changes sampling rate of the accelerometer device.
Only values which are supported by HW are accepted.
-selftest - performs selftest for the chip as specified by chip manufacturer.
+selftest
+ - performs selftest for the chip as specified by chip manufacturer.
This driver also provides an absolute input class device, allowing
the laptop to act as a pinball machine-esque joystick. Joystick device can be
@@ -69,11 +74,12 @@ Axes orientation
For better compatibility between the various laptops. The values reported by
the accelerometer are converted into a "standard" organisation of the axes
(aka "can play neverball out of the box"):
+
* When the laptop is horizontal the position reported is about 0 for X and Y
- and a positive value for Z
+ and a positive value for Z
* If the left side is elevated, X increases (becomes positive)
* If the front side (where the touchpad is) is elevated, Y decreases
- (becomes negative)
+ (becomes negative)
* If the laptop is put upside-down, Z becomes negative
If your laptop model is not recognized (cf "dmesg"), you can send an
diff --git a/Documentation/misc-devices/max6875 b/Documentation/misc-devices/max6875.rst
similarity index 83%
rename from Documentation/misc-devices/max6875
rename to Documentation/misc-devices/max6875.rst
index 2f2bd0b17b5d..ad419ac22a5b 100644
--- a/Documentation/misc-devices/max6875
+++ b/Documentation/misc-devices/max6875.rst
@@ -1,12 +1,16 @@
+=====================
Kernel driver max6875
=====================
Supported chips:
+
* Maxim MAX6874, MAX6875
+
Prefix: 'max6875'
+
Addresses scanned: None (see below)
- Datasheet:
- http://pdfserv.maxim-ic.com/en/ds/MAX6874-MAX6875.pdf
+
+ Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6874-MAX6875.pdf
Author: Ben Gardner <bgardner@wabtec.com>
@@ -24,9 +28,13 @@ registers.
The Maxim MAX6874 is a similar, mostly compatible device, with more inputs
and outputs:
- vin gpi vout
+
+=========== === === ====
+- vin gpi vout
+=========== === === ====
MAX6874 6 4 8
MAX6875 4 3 5
+=========== === === ====
See the datasheet for more information.
@@ -41,13 +49,16 @@ General Remarks
---------------
Valid addresses for the MAX6875 are 0x50 and 0x52.
+
Valid addresses for the MAX6874 are 0x50, 0x52, 0x54 and 0x56.
+
The driver does not probe any address, so you explicitly instantiate the
devices.
-Example:
-$ modprobe max6875
-$ echo max6875 0x50 > /sys/bus/i2c/devices/i2c-0/new_device
+Example::
+
+ $ modprobe max6875
+ $ echo max6875 0x50 > /sys/bus/i2c/devices/i2c-0/new_device
The MAX6874/MAX6875 ignores address bit 0, so this driver attaches to multiple
addresses. For example, for address 0x50, it also reserves 0x51.
@@ -58,52 +69,67 @@ Programming the chip using i2c-dev
----------------------------------
Use the i2c-dev interface to access and program the chips.
+
Reads and writes are performed differently depending on the address range.
The configuration registers are at addresses 0x00 - 0x45.
+
Use i2c_smbus_write_byte_data() to write a register and
i2c_smbus_read_byte_data() to read a register.
+
The command is the register number.
Examples:
-To write a 1 to register 0x45:
+
+To write a 1 to register 0x45::
+
i2c_smbus_write_byte_data(fd, 0x45, 1);
-To read register 0x45:
+To read register 0x45::
+
value = i2c_smbus_read_byte_data(fd, 0x45);
The configuration EEPROM is at addresses 0x8000 - 0x8045.
+
The user EEPROM is at addresses 0x8100 - 0x82ff.
Use i2c_smbus_write_word_data() to write a byte to EEPROM.
The command is the upper byte of the address: 0x80, 0x81, or 0x82.
-The data word is the lower part of the address or'd with data << 8.
+The data word is the lower part of the address or'd with data << 8::
+
cmd = address >> 8;
val = (address & 0xff) | (data << 8);
Example:
-To write 0x5a to address 0x8003:
+
+To write 0x5a to address 0x8003::
+
i2c_smbus_write_word_data(fd, 0x80, 0x5a03);
Reading data from the EEPROM is a little more complicated.
+
Use i2c_smbus_write_byte_data() to set the read address and then
i2c_smbus_read_byte() or i2c_smbus_read_i2c_block_data() to read the data.
Example:
-To read data starting at offset 0x8100, first set the address:
+
+To read data starting at offset 0x8100, first set the address::
+
i2c_smbus_write_byte_data(fd, 0x81, 0x00);
-And then read the data
+And then read the data::
+
value = i2c_smbus_read_byte(fd);
- or
+or::
count = i2c_smbus_read_i2c_block_data(fd, 0x84, 16, buffer);
The block read should read 16 bytes.
+
0x84 is the block read command.
See the datasheet for more details.
diff --git a/MAINTAINERS b/MAINTAINERS
index a49698b3becd..5d4da1035a03 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8956,7 +8956,7 @@ F: include/linux/leds.h
LEGACY EEPROM DRIVER
M: Jean Delvare <jdelvare@suse.com>
S: Maintained
-F: Documentation/misc-devices/eeprom
+F: Documentation/misc-devices/eeprom.rst
F: drivers/misc/eeprom/eeprom.c
LEGO MINDSTORMS EV3
@@ -9242,7 +9242,7 @@ F: Documentation/memory-barriers.txt
LIS3LV02D ACCELEROMETER DRIVER
M: Eric Piel <eric.piel@tremplin-utc.net>
S: Maintained
-F: Documentation/misc-devices/lis3lv02d
+F: Documentation/misc-devices/lis3lv02d.rst
F: drivers/misc/lis3lv02d/
F: drivers/platform/x86/hp_accel.c
diff --git a/drivers/misc/isl29003.c b/drivers/misc/isl29003.c
index 5d0d0c3bad85..c12406f610d5 100644
--- a/drivers/misc/isl29003.c
+++ b/drivers/misc/isl29003.c
@@ -3,7 +3,7 @@
* isl29003.c - Linux kernel module for
* Intersil ISL29003 ambient light sensor
*
- * See file:Documentation/misc-devices/isl29003
+ * See file:Documentation/misc-devices/isl29003.rst
*
* Copyright (c) 2009 Daniel Mack <daniel@caiaq.de>
*
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index e09aa0087024..7fdfe107fe33 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -341,7 +341,7 @@ config HP_ACCEL
Support for a led indicating disk protection will be provided as
hp::hddprotect. For more information on the feature, refer to
- Documentation/misc-devices/lis3lv02d.
+ Documentation/misc-devices/lis3lv02d.rst.
To compile this driver as a module, choose M here: the module will
be called hp_accel.
--
2.21.0
^ permalink raw reply related [flat|nested] 14+ messages in thread
* [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
2019-06-28 21:23 [PATCH 0/5] Convert misc-devices, i2c, w1, spi and some markdown files to ReST Mauro Carvalho Chehab
2019-06-28 21:23 ` [PATCH 1/5] docs: convert markdown documents " Mauro Carvalho Chehab
2019-06-28 21:23 ` [PATCH 2/5] docs: misc-devices: convert files without extension " Mauro Carvalho Chehab
@ 2019-06-28 21:23 ` Mauro Carvalho Chehab
2019-06-28 21:41 ` Alexandre Belloni
` (3 more replies)
2019-06-28 21:23 ` [PATCH 4/5] docs: w1: convert to ReST and add to the kAPI group of docs Mauro Carvalho Chehab
2019-06-28 21:23 ` [PATCH 5/5] docs: spi: convert to ReST and add it to the kABI bookset Mauro Carvalho Chehab
4 siblings, 4 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 21:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, Alessandro Zummo,
Alexandre Belloni, linux-i2c, devicetree, linux-hwmon, linux-spi,
linux-iio, linux-rtc
Convert each file at I2C subsystem, renaming them to .rst and
adding to the driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/IPMB.txt | 2 +-
.../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +-
Documentation/hwmon/adm1021.rst | 2 +-
Documentation/hwmon/adm1275.rst | 2 +-
Documentation/hwmon/hih6130.rst | 2 +-
Documentation/hwmon/ibm-cffps.rst | 2 +-
Documentation/hwmon/lm25066.rst | 2 +-
Documentation/hwmon/max16064.rst | 2 +-
Documentation/hwmon/max16065.rst | 2 +-
Documentation/hwmon/max20751.rst | 2 +-
Documentation/hwmon/max34440.rst | 2 +-
Documentation/hwmon/max6650.rst | 2 +-
Documentation/hwmon/max8688.rst | 2 +-
Documentation/hwmon/menf21bmc.rst | 2 +-
Documentation/hwmon/pcf8591.rst | 2 +-
Documentation/hwmon/sht3x.rst | 2 +-
Documentation/hwmon/shtc1.rst | 2 +-
Documentation/hwmon/tmp103.rst | 2 +-
Documentation/hwmon/tps40422.rst | 2 +-
Documentation/hwmon/ucd9000.rst | 2 +-
Documentation/hwmon/ucd9200.rst | 2 +-
Documentation/hwmon/via686a.rst | 2 +-
Documentation/hwmon/zl6100.rst | 2 +-
.../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +-
.../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 +
.../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 63 +++---
Documentation/i2c/busses/i2c-amd-mp2 | 23 ---
Documentation/i2c/busses/i2c-amd-mp2.rst | 25 +++
.../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +-
.../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +-
.../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 +
.../i2c/busses/{i2c-i801 => i2c-i801.rst} | 31 ++-
.../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +-
.../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 +
.../busses/{i2c-nforce2 => i2c-nforce2.rst} | 23 ++-
.../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +-
.../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +-
Documentation/i2c/busses/i2c-parport | 178 ----------------
...2c-parport-light => i2c-parport-light.rst} | 2 +
Documentation/i2c/busses/i2c-parport.rst | 190 +++++++++++++++++
.../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +-
.../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 14 +-
.../busses/{i2c-sis5595 => i2c-sis5595.rst} | 18 +-
Documentation/i2c/busses/i2c-sis630 | 58 ------
Documentation/i2c/busses/i2c-sis630.rst | 64 ++++++
.../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 28 ++-
.../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +-
.../i2c/busses/{i2c-via => i2c-via.rst} | 20 +-
.../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +-
Documentation/i2c/busses/index.rst | 33 +++
.../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +-
.../i2c/{dev-interface => dev-interface.rst} | 94 +++++----
...-considerations => dma-considerations.rst} | 0
.../i2c/{fault-codes => fault-codes.rst} | 4 +
.../i2c/{functionality => functionality.rst} | 18 +-
...ult-injection => gpio-fault-injection.rst} | 12 +-
.../i2c/{i2c-protocol => i2c-protocol.rst} | 28 ++-
Documentation/i2c/{i2c-stub => i2c-stub.rst} | 19 +-
.../i2c/{i2c-topology => i2c-topology.rst} | 68 +++---
Documentation/i2c/index.rst | 38 ++++
...ting-devices => instantiating-devices.rst} | 45 ++--
.../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +--
...e-parameters => old-module-parameters.rst} | 27 ++-
...eprom-backend => slave-eeprom-backend.rst} | 3 +-
.../{slave-interface => slave-interface.rst} | 32 +--
.../{smbus-protocol => smbus-protocol.rst} | 74 ++++---
Documentation/i2c/{summary => summary.rst} | 4 +-
...en-bit-addresses => ten-bit-addresses.rst} | 5 +
...pgrading-clients => upgrading-clients.rst} | 194 +++++++++---------
.../{writing-clients => writing-clients.rst} | 94 +++++----
Documentation/index.rst | 1 +
Documentation/spi/spi-sc18is602 | 2 +-
MAINTAINERS | 48 ++---
Next/merge.log | 6 +-
drivers/hwmon/atxp1.c | 2 +-
drivers/hwmon/smm665.c | 2 +-
drivers/i2c/Kconfig | 4 +-
drivers/i2c/busses/Kconfig | 2 +-
drivers/i2c/busses/i2c-i801.c | 2 +-
drivers/i2c/busses/i2c-taos-evm.c | 2 +-
drivers/i2c/i2c-core-base.c | 4 +-
drivers/iio/dummy/iio_simple_dummy.c | 2 +-
drivers/rtc/rtc-ds1374.c | 2 +-
include/linux/i2c.h | 2 +-
84 files changed, 1065 insertions(+), 750 deletions(-)
rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
delete mode 100644 Documentation/i2c/busses/i2c-amd-mp2
create mode 100644 Documentation/i2c/busses/i2c-amd-mp2.rst
rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (68%)
rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
delete mode 100644 Documentation/i2c/busses/i2c-parport
rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (92%)
create mode 100644 Documentation/i2c/busses/i2c-parport.rst
rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
delete mode 100644 Documentation/i2c/busses/i2c-sis630
create mode 100644 Documentation/i2c/busses/i2c-sis630.rst
rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (75%)
rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (61%)
rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
create mode 100644 Documentation/i2c/busses/index.rst
rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
rename Documentation/i2c/{functionality => functionality.rst} (91%)
rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
create mode 100644 Documentation/i2c/index.rst
rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (84%)
rename Documentation/i2c/{summary => summary.rst} (96%)
rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (56%)
rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
diff --git a/Documentation/IPMB.txt b/Documentation/IPMB.txt
index a6ed8b68bd0f..cd20c9764705 100644
--- a/Documentation/IPMB.txt
+++ b/Documentation/IPMB.txt
@@ -82,7 +82,7 @@ Instantiate the device
----------------------
After loading the driver, you can instantiate the device as
-described in 'Documentation/i2c/instantiating-devices'.
+described in 'Documentation/i2c/instantiating-devices.rst'.
If you have multiple BMCs, each connected to your Satellite MC via
a different I2C bus, you can instantiate a device for each of
those BMCs.
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
index 2907dab56298..8b444b94e92f 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
@@ -42,7 +42,7 @@ Optional properties:
This means that no unrelated I2C transactions are allowed on the parent I2C
adapter for the complete multiplexed I2C transaction.
The properties of mux-locked and parent-locked multiplexers are discussed
- in more detail in Documentation/i2c/i2c-topology.
+ in more detail in Documentation/i2c/i2c-topology.rst.
For each i2c child node, an I2C child bus will be created. They will
be numbered based on their order in the device tree.
diff --git a/Documentation/hwmon/adm1021.rst b/Documentation/hwmon/adm1021.rst
index 6cbb0f75fe00..116fb2019956 100644
--- a/Documentation/hwmon/adm1021.rst
+++ b/Documentation/hwmon/adm1021.rst
@@ -142,7 +142,7 @@ loading the adm1021 module, then things are good.
If nothing happens when loading the adm1021 module, and you are certain
that your specific Xeon processor model includes compatible sensors, you
will have to explicitly instantiate the sensor chips from user-space. See
-method 4 in Documentation/i2c/instantiating-devices. Possible slave
+method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave
addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that
only temp2 will be correct and temp1 will have to be ignored.
diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst
index 9a1913e5b4d9..49966ed70ec6 100644
--- a/Documentation/hwmon/adm1275.rst
+++ b/Documentation/hwmon/adm1275.rst
@@ -75,7 +75,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
The ADM1075, unlike many other PMBus devices, does not support internal voltage
diff --git a/Documentation/hwmon/hih6130.rst b/Documentation/hwmon/hih6130.rst
index 649bd4be4fc2..e95d373eb693 100644
--- a/Documentation/hwmon/hih6130.rst
+++ b/Documentation/hwmon/hih6130.rst
@@ -27,7 +27,7 @@ The devices communicate with the I2C protocol. All sensors are set to the same
I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27)
can be used in the board setup code.
-Please see Documentation/i2c/instantiating-devices for details on how to
+Please see Documentation/i2c/instantiating-devices.rst for details on how to
instantiate I2C devices.
sysfs-Interface
diff --git a/Documentation/hwmon/ibm-cffps.rst b/Documentation/hwmon/ibm-cffps.rst
index 52e74e39463a..ef8f3f806968 100644
--- a/Documentation/hwmon/ibm-cffps.rst
+++ b/Documentation/hwmon/ibm-cffps.rst
@@ -17,7 +17,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
Sysfs entries
diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst
index da15e3094c8c..30e6e77fb3c8 100644
--- a/Documentation/hwmon/lm25066.rst
+++ b/Documentation/hwmon/lm25066.rst
@@ -76,7 +76,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/max16064.rst b/Documentation/hwmon/max16064.rst
index 6d5e9538991f..c06249292557 100644
--- a/Documentation/hwmon/max16064.rst
+++ b/Documentation/hwmon/max16064.rst
@@ -28,7 +28,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/max16065.rst b/Documentation/hwmon/max16065.rst
index fa5c852a178c..45f69f334f25 100644
--- a/Documentation/hwmon/max16065.rst
+++ b/Documentation/hwmon/max16065.rst
@@ -79,7 +79,7 @@ Usage Notes
This driver does not probe for devices, since there is no register which
can be safely used to identify the chip. You will have to instantiate
-the devices explicitly. Please see Documentation/i2c/instantiating-devices for
+the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
WARNING: Do not access chip registers using the i2cdump command, and do not use
diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst
index aa4469be6674..fe701e07eaf5 100644
--- a/Documentation/hwmon/max20751.rst
+++ b/Documentation/hwmon/max20751.rst
@@ -30,7 +30,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst
index 939138e12b02..5744df100a5d 100644
--- a/Documentation/hwmon/max34440.rst
+++ b/Documentation/hwmon/max34440.rst
@@ -83,7 +83,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
For MAX34446, the value of the currX_crit attribute determines if current or
diff --git a/Documentation/hwmon/max6650.rst b/Documentation/hwmon/max6650.rst
index 253482add082..7952b6ecaa2d 100644
--- a/Documentation/hwmon/max6650.rst
+++ b/Documentation/hwmon/max6650.rst
@@ -55,7 +55,7 @@ Usage notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
Module parameters
diff --git a/Documentation/hwmon/max8688.rst b/Documentation/hwmon/max8688.rst
index 009487759c61..71e7f2cbe2e2 100644
--- a/Documentation/hwmon/max8688.rst
+++ b/Documentation/hwmon/max8688.rst
@@ -28,7 +28,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/menf21bmc.rst b/Documentation/hwmon/menf21bmc.rst
index 1f0c6b2235ab..978691d5956d 100644
--- a/Documentation/hwmon/menf21bmc.rst
+++ b/Documentation/hwmon/menf21bmc.rst
@@ -28,7 +28,7 @@ Usage Notes
This driver is part of the MFD driver named "menf21bmc" and does
not auto-detect devices.
You will have to instantiate the MFD driver explicitly.
-Please see Documentation/i2c/instantiating-devices for
+Please see Documentation/i2c/instantiating-devices.rst for
details.
Sysfs entries
diff --git a/Documentation/hwmon/pcf8591.rst b/Documentation/hwmon/pcf8591.rst
index e98bd542a441..5c4e85f53177 100644
--- a/Documentation/hwmon/pcf8591.rst
+++ b/Documentation/hwmon/pcf8591.rst
@@ -68,7 +68,7 @@ Accessing PCF8591 via /sys interface
The PCF8591 is plainly impossible to detect! Thus the driver won't even
try. You have to explicitly instantiate the device at the relevant
address (in the interval [0x48..0x4f]) either through platform data, or
-using the sysfs interface. See Documentation/i2c/instantiating-devices
+using the sysfs interface. See Documentation/i2c/instantiating-devices.rst
for details.
Directories are being created for each instantiated PCF8591:
diff --git a/Documentation/hwmon/sht3x.rst b/Documentation/hwmon/sht3x.rst
index 978a7117e4b2..95a850d5b2c1 100644
--- a/Documentation/hwmon/sht3x.rst
+++ b/Documentation/hwmon/sht3x.rst
@@ -26,7 +26,7 @@ scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500.
The device communicates with the I2C protocol. Sensors can have the I2C
addresses 0x44 or 0x45, depending on the wiring. See
-Documentation/i2c/instantiating-devices for methods to instantiate the device.
+Documentation/i2c/instantiating-devices.rst for methods to instantiate the device.
There are two options configurable by means of sht3x_platform_data:
diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst
index aa116332ba26..70c1192bbd8c 100644
--- a/Documentation/hwmon/shtc1.rst
+++ b/Documentation/hwmon/shtc1.rst
@@ -36,7 +36,7 @@ humidity is expressed as a percentage. Driver can be used as well for SHTW1
chip, which has the same electrical interface.
The device communicates with the I2C protocol. All sensors are set to I2C
-address 0x70. See Documentation/i2c/instantiating-devices for methods to
+address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to
instantiate the device.
There are two options configurable by means of shtc1_platform_data:
diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst
index 15d25806d585..205de6148fcb 100644
--- a/Documentation/hwmon/tmp103.rst
+++ b/Documentation/hwmon/tmp103.rst
@@ -30,4 +30,4 @@ The driver provides the common sysfs-interface for temperatures (see
Documentation/hwmon/sysfs-interface.rst under Temperatures).
Please refer how to instantiate this driver:
-Documentation/i2c/instantiating-devices
+Documentation/i2c/instantiating-devices.rst
diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst
index b691e30479dd..8fe3e1c3572e 100644
--- a/Documentation/hwmon/tps40422.rst
+++ b/Documentation/hwmon/tps40422.rst
@@ -28,7 +28,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/ucd9000.rst b/Documentation/hwmon/ucd9000.rst
index ebc4f2b3bfea..746f21fcb48c 100644
--- a/Documentation/hwmon/ucd9000.rst
+++ b/Documentation/hwmon/ucd9000.rst
@@ -64,7 +64,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/ucd9200.rst b/Documentation/hwmon/ucd9200.rst
index b819dfd75f71..4f0e7c3ca6f4 100644
--- a/Documentation/hwmon/ucd9200.rst
+++ b/Documentation/hwmon/ucd9200.rst
@@ -40,7 +40,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/via686a.rst b/Documentation/hwmon/via686a.rst
index a343c35df740..7ab9ddebcf79 100644
--- a/Documentation/hwmon/via686a.rst
+++ b/Documentation/hwmon/via686a.rst
@@ -40,7 +40,7 @@ all as a 686A.
The Via 686a southbridge has integrated hardware monitor functionality.
It also has an I2C bus, but this driver only supports the hardware monitor.
-For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro>
+For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro.rst>
The Via 686a implements three temperature sensors, two fan rotation speed
sensors, five voltage sensors and alarms.
diff --git a/Documentation/hwmon/zl6100.rst b/Documentation/hwmon/zl6100.rst
index 41513bb7fe51..968aff10ce0a 100644
--- a/Documentation/hwmon/zl6100.rst
+++ b/Documentation/hwmon/zl6100.rst
@@ -121,7 +121,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
.. warning::
diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535.rst
similarity index 82%
rename from Documentation/i2c/busses/i2c-ali1535
rename to Documentation/i2c/busses/i2c-ali1535.rst
index 5d46342e486a..6941064730dc 100644
--- a/Documentation/i2c/busses/i2c-ali1535
+++ b/Documentation/i2c/busses/i2c-ali1535.rst
@@ -1,16 +1,19 @@
+=========================
Kernel driver i2c-ali1535
+=========================
Supported adapters:
* Acer Labs, Inc. ALI 1535 (south bridge)
+
Datasheet: Now under NDA
http://www.ali.com.tw/
Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>,
- Dan Eaton <dan.eaton@rocketlogix.com>,
- Stephen Rousset<stephen.rousset@rocketlogix.com>
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Philip Edelbrock <phil@netroedge.com>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+ - Dan Eaton <dan.eaton@rocketlogix.com>,
+ - Stephen Rousset<stephen.rousset@rocketlogix.com>
Description
-----------
diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563.rst
similarity index 93%
rename from Documentation/i2c/busses/i2c-ali1563
rename to Documentation/i2c/busses/i2c-ali1563.rst
index 41b1a077e4c7..eec32c3ba92a 100644
--- a/Documentation/i2c/busses/i2c-ali1563
+++ b/Documentation/i2c/busses/i2c-ali1563.rst
@@ -1,7 +1,10 @@
+=========================
Kernel driver i2c-ali1563
+=========================
Supported adapters:
* Acer Labs, Inc. ALI 1563 (south bridge)
+
Datasheet: Now under NDA
http://www.ali.com.tw/
diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3.rst
similarity index 72%
rename from Documentation/i2c/busses/i2c-ali15x3
rename to Documentation/i2c/busses/i2c-ali15x3.rst
index 42888d8ac124..c70f7c66db51 100644
--- a/Documentation/i2c/busses/i2c-ali15x3
+++ b/Documentation/i2c/busses/i2c-ali15x3.rst
@@ -1,20 +1,23 @@
+=========================
Kernel driver i2c-ali15x3
+=========================
Supported adapters:
* Acer Labs, Inc. ALI 1533 and 1543C (south bridge)
+
Datasheet: Now under NDA
http://www.ali.com.tw/
Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Philip Edelbrock <phil@netroedge.com>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>
Module Parameters
-----------------
* force_addr: int
- Initialize the base address of the i2c controller
+ Initialize the base address of the i2c controller
Notes
@@ -25,7 +28,9 @@ the BIOS. Does not do a PCI force; the device must still be present in
lspci. Don't use this unless the driver complains that the base address is
not set.
-Example: 'modprobe i2c-ali15x3 force_addr=0xe800'
+Example::
+
+ modprobe i2c-ali15x3 force_addr=0xe800
SMBus periodically hangs on ASUS P5A motherboards and can only be cleared
by a power cycle. Cause unknown (see Issues below).
@@ -38,47 +43,53 @@ This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
M1541 and M1543C South Bridges.
The M1543C is a South bridge for desktop systems.
+
The M1541 is a South bridge for portable systems.
+
They are part of the following ALI chipsets:
* "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and
- 100MHz CPU Front Side bus
+ 100MHz CPU Front Side bus
* "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz
- CPU Front Side bus
+ CPU Front Side bus
+
Some Aladdin V motherboards:
- Asus P5A
- Atrend ATC-5220
- BCM/GVC VP1541
- Biostar M5ALA
- Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't
- enable the 7101 device! **)
- Iwill XA100 Plus
- Micronics C200
- Microstar (MSI) MS-5169
+ - Asus P5A
+ - Atrend ATC-5220
+ - BCM/GVC VP1541
+ - Biostar M5ALA
+ - Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't
+ enable the 7101 device!)
+ - Iwill XA100 Plus
+ - Micronics C200
+ - Microstar (MSI) MS-5169
* "Aladdin IV" includes the M1541 Socket 7 North bridge
- with host bus up to 83.3 MHz.
+ with host bus up to 83.3 MHz.
For an overview of these chips see http://www.acerlabs.com. At this time the
full data sheets on the web site are password protected, however if you
contact the ALI office in San Jose they may give you the password.
The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An
-output of lspci will show something similar to the following:
+output of lspci will show something similar to the following::
00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03)
00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED
00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3)
00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1)
-** IMPORTANT **
-** If you have a M1533 or M1543C on the board and you get
-** "ali15x3: Error: Can't detect ali15x3!"
-** then run lspci.
-** If you see the 1533 and 5229 devices but NOT the 7101 device,
-** then you must enable ACPI, the PMU, SMB, or something similar
-** in the BIOS.
-** The driver won't work if it can't find the M7101 device.
+.. important::
+
+ If you have a M1533 or M1543C on the board and you get
+ "ali15x3: Error: Can't detect ali15x3!"
+ then run lspci.
+
+ If you see the 1533 and 5229 devices but NOT the 7101 device,
+ then you must enable ACPI, the PMU, SMB, or something similar
+ in the BIOS.
+
+ The driver won't work if it can't find the M7101 device.
The SMB controller is part of the M7101 device, which is an ACPI-compliant
Power Management Unit (PMU).
diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2
deleted file mode 100644
index 6571487171f4..000000000000
--- a/Documentation/i2c/busses/i2c-amd-mp2
+++ /dev/null
@@ -1,23 +0,0 @@
-Kernel driver i2c-amd-mp2
-
-Supported adapters:
- * AMD MP2 PCIe interface
-
-Datasheet: not publicly available.
-
-Authors:
- Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
- Nehal Shah <nehal-bakulchandra.shah@amd.com>
- Elie Morisse <syniurge@gmail.com>
-
-Description
------------
-
-The MP2 is an ARM processor programmed as an I2C controller and communicating
-with the x86 host through PCI.
-
-If you see something like this:
-
-03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
-
-in your 'lspci -v', then this driver is for your device.
diff --git a/Documentation/i2c/busses/i2c-amd-mp2.rst b/Documentation/i2c/busses/i2c-amd-mp2.rst
new file mode 100644
index 000000000000..ebc2fa899325
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-amd-mp2.rst
@@ -0,0 +1,25 @@
+=========================
+Kernel driver i2c-amd-mp2
+=========================
+
+Supported adapters:
+ * AMD MP2 PCIe interface
+
+Datasheet: not publicly available.
+
+Authors:
+ - Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
+ - Nehal Shah <nehal-bakulchandra.shah@amd.com>
+ - Elie Morisse <syniurge@gmail.com>
+
+Description
+-----------
+
+The MP2 is an ARM processor programmed as an I2C controller and communicating
+with the x86 host through PCI.
+
+If you see something like this::
+
+ 03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
+
+in your ``lspci -v``, then this driver is for your device.
diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756.rst
similarity index 79%
rename from Documentation/i2c/busses/i2c-amd756
rename to Documentation/i2c/busses/i2c-amd756.rst
index 67f30874d0bf..bc93f392a4fc 100644
--- a/Documentation/i2c/busses/i2c-amd756
+++ b/Documentation/i2c/busses/i2c-amd756.rst
@@ -1,18 +1,22 @@
+========================
Kernel driver i2c-amd756
+========================
Supported adapters:
* AMD 756
* AMD 766
* AMD 768
* AMD 8111
+
Datasheets: Publicly available on AMD website
* nVidia nForce
+
Datasheet: Unavailable
Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Philip Edelbrock <phil@netroedge.com>
Description
-----------
diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111.rst
similarity index 66%
rename from Documentation/i2c/busses/i2c-amd8111
rename to Documentation/i2c/busses/i2c-amd8111.rst
index 460dd6635fd2..d08bf0a7f0ac 100644
--- a/Documentation/i2c/busses/i2c-amd8111
+++ b/Documentation/i2c/busses/i2c-amd8111.rst
@@ -1,4 +1,6 @@
+=========================
Kernel driver i2c-adm8111
+=========================
Supported adapters:
* AMD-8111 SMBus 2.0 PCI interface
@@ -13,14 +15,14 @@ Author: Vojtech Pavlik <vojtech@suse.cz>
Description
-----------
-If you see something like this:
+If you see something like this::
-00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
- Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
- Flags: medium devsel, IRQ 19
- I/O ports at d400 [size=32]
+ 00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
+ Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
+ Flags: medium devsel, IRQ 19
+ I/O ports at d400 [size=32]
-in your 'lspci -v', then this driver is for your chipset.
+in your ``lspci -v``, then this driver is for your chipset.
Process Call Support
--------------------
diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c.rst
similarity index 91%
rename from Documentation/i2c/busses/i2c-diolan-u2c
rename to Documentation/i2c/busses/i2c-diolan-u2c.rst
index 0d6018c316c7..c18cbdcdf73c 100644
--- a/Documentation/i2c/busses/i2c-diolan-u2c
+++ b/Documentation/i2c/busses/i2c-diolan-u2c.rst
@@ -1,7 +1,10 @@
+============================
Kernel driver i2c-diolan-u2c
+============================
Supported adapters:
* Diolan U2C-12 I2C-USB adapter
+
Documentation:
http://www.diolan.com/i2c/u2c12.html
diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801.rst
similarity index 89%
rename from Documentation/i2c/busses/i2c-i801
rename to Documentation/i2c/busses/i2c-i801.rst
index d247edcb0f99..976b42a15129 100644
--- a/Documentation/i2c/busses/i2c-i801
+++ b/Documentation/i2c/busses/i2c-i801.rst
@@ -1,4 +1,7 @@
+======================
Kernel driver i2c-i801
+======================
+
Supported adapters:
* Intel 82801AA and 82801AB (ICH and ICH0 - part of the
@@ -38,27 +41,32 @@ Supported adapters:
* Intel Ice Lake (PCH)
* Intel Comet Lake (PCH)
* Intel Elkhart Lake (PCH)
+
Datasheets: Publicly available at the Intel website
On Intel Patsburg and later chipsets, both the normal host SMBus controller
and the additional 'Integrated Device Function' controllers are supported.
Authors:
- Mark Studebaker <mdsxyz123@yahoo.com>
- Jean Delvare <jdelvare@suse.de>
+ - Mark Studebaker <mdsxyz123@yahoo.com>
+ - Jean Delvare <jdelvare@suse.de>
Module Parameters
-----------------
* disable_features (bit vector)
+
Disable selected features normally supported by the device. This makes it
possible to work around possible driver or hardware bugs if the feature in
question doesn't work as intended for whatever reason. Bit values:
+
+ ==== =========================================
0x01 disable SMBus PEC
0x02 disable the block buffer
0x08 disable the I2C block read functionality
0x10 don't use interrupts
+ ==== =========================================
Description
@@ -71,7 +79,7 @@ Pentium-based PCs, '815E' chipset, and others.
The ICH chips contain at least SEVEN separate PCI functions in TWO logical
PCI devices. An output of lspci will show something similar to the
-following:
+following::
00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01)
00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01)
@@ -138,14 +146,14 @@ and you think there's something interesting on the SMBus (e.g. a
hardware monitoring chip), you need to add your board to the list.
The motherboard is identified using the subvendor and subdevice IDs of the
-host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0":
+host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``::
-00:00.0 Class 0600: 8086:2570 (rev 02)
- Subsystem: 1043:80f2
- Flags: bus master, fast devsel, latency 0
- Memory at fc000000 (32-bit, prefetchable) [size=32M]
- Capabilities: [e4] #09 [2106]
- Capabilities: [a0] AGP version 3.0
+ 00:00.0 Class 0600: 8086:2570 (rev 02)
+ Subsystem: 1043:80f2
+ Flags: bus master, fast devsel, latency 0
+ Memory at fc000000 (32-bit, prefetchable) [size=32M]
+ Capabilities: [e4] #09 [2106]
+ Capabilities: [a0] AGP version 3.0
Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043
(Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic
@@ -164,7 +172,8 @@ kernel. It's very convenient if you just want to check if there's
anything interesting on your hidden ICH SMBus.
-**********************
+----------------------------------------------------------------------------
+
The lm_sensors project gratefully acknowledges the support of Texas
Instruments in the initial development of this driver.
diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt.rst
similarity index 81%
rename from Documentation/i2c/busses/i2c-ismt
rename to Documentation/i2c/busses/i2c-ismt.rst
index 737355822c0b..8e74919a3fdf 100644
--- a/Documentation/i2c/busses/i2c-ismt
+++ b/Documentation/i2c/busses/i2c-ismt.rst
@@ -1,4 +1,7 @@
+======================
Kernel driver i2c-ismt
+======================
+
Supported adapters:
* Intel S12xx series SOCs
@@ -11,16 +14,21 @@ Module Parameters
-----------------
* bus_speed (unsigned int)
+
Allows changing of the bus speed. Normally, the bus speed is set by the BIOS
and never needs to be changed. However, some SMBus analyzers are too slow for
monitoring the bus during debug, thus the need for this module parameter.
Specify the bus speed in kHz.
+
Available bus frequency settings:
- 0 no change
- 80 kHz
- 100 kHz
- 400 kHz
- 1000 kHz
+
+ ==== =========
+ 0 no change
+ 80 kHz
+ 100 kHz
+ 400 kHz
+ 1000 kHz
+ ==== =========
Description
@@ -30,7 +38,7 @@ The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers
targeted primarily at the microserver and storage markets.
The S12xx series contain a pair of PCI functions. An output of lspci will show
-something similar to the following:
+something similar to the following::
00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0
00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1
diff --git a/Documentation/i2c/busses/i2c-mlxcpld b/Documentation/i2c/busses/i2c-mlxcpld.rst
similarity index 88%
rename from Documentation/i2c/busses/i2c-mlxcpld
rename to Documentation/i2c/busses/i2c-mlxcpld.rst
index 925904aa9b57..9a0b2916aa71 100644
--- a/Documentation/i2c/busses/i2c-mlxcpld
+++ b/Documentation/i2c/busses/i2c-mlxcpld.rst
@@ -1,9 +1,12 @@
+==================
Driver i2c-mlxcpld
+==================
Author: Michael Shych <michaelsh@mellanox.com>
This is the Mellanox I2C controller logic, implemented in Lattice CPLD
device.
+
Device supports:
- Master mode.
- One physical bus.
@@ -20,6 +23,8 @@ The next transaction types are supported:
- Write Byte/Block.
Registers:
+
+=============== === =======================================================================
CPBLTY 0x0 - capability reg.
Bits [6:5] - transaction length. b01 - 72B is supported,
36B in other case.
@@ -49,3 +54,4 @@ DATAx 0xa - 0x54 - 68 bytes data buffer regs.
For read transactions address is sent in a separate transaction and
specified in the four first bytes (DATA0 - DATA3). Data is read
starting from DATA0.
+=============== === =======================================================================
diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2.rst
similarity index 68%
rename from Documentation/i2c/busses/i2c-nforce2
rename to Documentation/i2c/busses/i2c-nforce2.rst
index 9698c396b830..f5c57ea31cd3 100644
--- a/Documentation/i2c/busses/i2c-nforce2
+++ b/Documentation/i2c/busses/i2c-nforce2.rst
@@ -1,4 +1,6 @@
+=========================
Kernel driver i2c-nforce2
+=========================
Supported adapters:
* nForce2 MCP 10de:0064
@@ -16,26 +18,27 @@ Supported adapters:
* nForce MCP78S 10de:0752
* nForce MCP79 10de:0AA2
-Datasheet: not publicly available, but seems to be similar to the
+Datasheet:
+ not publicly available, but seems to be similar to the
AMD-8111 SMBus 2.0 adapter.
Authors:
- Hans-Frieder Vogt <hfvogt@gmx.net>,
- Thomas Leibold <thomas@plx.com>,
- Patrick Dreker <patrick@dreker.de>
+ - Hans-Frieder Vogt <hfvogt@gmx.net>,
+ - Thomas Leibold <thomas@plx.com>,
+ - Patrick Dreker <patrick@dreker.de>
Description
-----------
i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP.
-If your 'lspci -v' listing shows something like the following,
+If your ``lspci -v`` listing shows something like the following::
-00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
- Subsystem: Asustek Computer, Inc.: Unknown device 0c11
- Flags: 66Mhz, fast devsel, IRQ 5
- I/O ports at c000 [size=32]
- Capabilities: <available only to root>
+ 00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
+ Subsystem: Asustek Computer, Inc.: Unknown device 0c11
+ Flags: 66Mhz, fast devsel, IRQ 5
+ I/O ports at c000 [size=32]
+ Capabilities: <available only to root>
then this driver should support the SMBuses of your motherboard.
diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
similarity index 63%
rename from Documentation/i2c/busses/i2c-nvidia-gpu
rename to Documentation/i2c/busses/i2c-nvidia-gpu.rst
index 31884d2b2eb5..38fb8a4c8756 100644
--- a/Documentation/i2c/busses/i2c-nvidia-gpu
+++ b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
@@ -1,4 +1,6 @@
+============================
Kernel driver i2c-nvidia-gpu
+============================
Datasheet: not publicly available.
@@ -11,8 +13,8 @@ Description
i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing
and later GPUs and it is used to communicate with Type-C controller on GPUs.
-If your 'lspci -v' listing shows something like the following,
+If your ``lspci -v`` listing shows something like the following::
-01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
+ 01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
then this driver should support the I2C controller of your GPU.
diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores.rst
similarity index 82%
rename from Documentation/i2c/busses/i2c-ocores
rename to Documentation/i2c/busses/i2c-ocores.rst
index 9caaf7df1b2f..f5e175f2a2a6 100644
--- a/Documentation/i2c/busses/i2c-ocores
+++ b/Documentation/i2c/busses/i2c-ocores.rst
@@ -1,4 +1,6 @@
+========================
Kernel driver i2c-ocores
+========================
Supported adapters:
* OpenCores.org I2C controller by Richard Herveille (see datasheet link)
@@ -23,9 +25,9 @@ distance between registers and the input clock speed.
There is also a possibility to attach a list of i2c_board_info which
the i2c-ocores driver will add to the bus upon creation.
-E.G. something like:
+E.G. something like::
-static struct resource ocores_resources[] = {
+ static struct resource ocores_resources[] = {
[0] = {
.start = MYI2C_BASEADDR,
.end = MYI2C_BASEADDR + 8,
@@ -36,10 +38,10 @@ static struct resource ocores_resources[] = {
.end = MYI2C_IRQ,
.flags = IORESOURCE_IRQ,
},
-};
+ };
-/* optional board info */
-struct i2c_board_info ocores_i2c_board_info[] = {
+ /* optional board info */
+ struct i2c_board_info ocores_i2c_board_info[] = {
{
I2C_BOARD_INFO("tsc2003", 0x48),
.platform_data = &tsc2003_platform_data,
@@ -49,20 +51,20 @@ struct i2c_board_info ocores_i2c_board_info[] = {
I2C_BOARD_INFO("adv7180", 0x42 >> 1),
.irq = ADV_IRQ
}
-};
+ };
-static struct ocores_i2c_platform_data myi2c_data = {
+ static struct ocores_i2c_platform_data myi2c_data = {
.regstep = 2, /* two bytes between registers */
.clock_khz = 50000, /* input clock of 50MHz */
.devices = ocores_i2c_board_info, /* optional table of devices */
.num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */
-};
+ };
-static struct platform_device myi2c = {
+ static struct platform_device myi2c = {
.name = "ocores-i2c",
.dev = {
.platform_data = &myi2c_data,
},
.num_resources = ARRAY_SIZE(ocores_resources),
.resource = ocores_resources,
-};
+ };
diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport
deleted file mode 100644
index c3dbb3bfd814..000000000000
--- a/Documentation/i2c/busses/i2c-parport
+++ /dev/null
@@ -1,178 +0,0 @@
-Kernel driver i2c-parport
-
-Author: Jean Delvare <jdelvare@suse.de>
-
-This is a unified driver for several i2c-over-parallel-port adapters,
-such as the ones made by Philips, Velleman or ELV. This driver is
-meant as a replacement for the older, individual drivers:
- * i2c-philips-par
- * i2c-elv
- * i2c-velleman
- * video/i2c-parport (NOT the same as this one, dedicated to home brew
- teletext adapters)
-
-It currently supports the following devices:
- * (type=0) Philips adapter
- * (type=1) home brew teletext adapter
- * (type=2) Velleman K8000 adapter
- * (type=3) ELV adapter
- * (type=4) Analog Devices ADM1032 evaluation board
- * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
- * (type=6) Barco LPT->DVI (K5800236) adapter
- * (type=7) One For All JP1 parallel port adapter
- * (type=8) VCT-jig
-
-These devices use different pinout configurations, so you have to tell
-the driver what you have, using the type module parameter. There is no
-way to autodetect the devices. Support for different pinout configurations
-can be easily added when needed.
-
-Earlier kernels defaulted to type=0 (Philips). But now, if the type
-parameter is missing, the driver will simply fail to initialize.
-
-SMBus alert support is available on adapters which have this line properly
-connected to the parallel port's interrupt pin.
-
-
-Building your own adapter
--------------------------
-
-If you want to build you own i2c-over-parallel-port adapter, here is
-a sample electronics schema (credits go to Sylvain Munaut):
-
-Device PC
-Side ___________________Vdd (+) Side
- | | |
- --- --- ---
- | | | | | |
- |R| |R| |R|
- | | | | | |
- --- --- ---
- | | |
- | | /| |
-SCL ----------x--------o |-----------x------------------- pin 2
- | \| | |
- | | |
- | |\ | |
-SDA ----------x----x---| o---x--------------------------- pin 13
- | |/ |
- | |
- | /| |
- ---------o |----------------x-------------- pin 3
- \| | |
- | |
- --- ---
- | | | |
- |R| |R|
- | | | |
- --- ---
- | |
- ### ###
- GND GND
-
-Remarks:
- - This is the exact pinout and electronics used on the Analog Devices
- evaluation boards.
- /|
- - All inverters -o |- must be 74HC05, they must be open collector output.
- \|
- - All resitors are 10k.
- - Pins 18-25 of the parallel port connected to GND.
- - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
- The ADM1032 evaluation board uses D4-D7. Beware that the amount of
- current you can draw from the parallel port is limited. Also note that
- all connected lines MUST BE driven at the same state, else you'll short
- circuit the output buffers! So plugging the I2C adapter after loading
- the i2c-parport module might be a good safety since data line state
- prior to init may be unknown.
- - This is 5V!
- - Obviously you cannot read SCL (so it's not really standard-compliant).
- Pretty easy to add, just copy the SDA part and use another input pin.
- That would give (ELV compatible pinout):
-
-
-Device PC
-Side ______________________________Vdd (+) Side
- | | | |
- --- --- --- ---
- | | | | | | | |
- |R| |R| |R| |R|
- | | | | | | | |
- --- --- --- ---
- | | | |
- | | |\ | |
-SCL ----------x--------x--| o---x------------------------ pin 15
- | | |/ |
- | | |
- | | /| |
- | ---o |-------------x-------------- pin 2
- | \| | |
- | | |
- | | |
- | |\ | |
-SDA ---------------x---x--| o--------x------------------- pin 10
- | |/ |
- | |
- | /| |
- ---o |------------------x--------- pin 3
- \| | |
- | |
- --- ---
- | | | |
- |R| |R|
- | | | |
- --- ---
- | |
- ### ###
- GND GND
-
-
-If possible, you should use the same pinout configuration as existing
-adapters do, so you won't even have to change the code.
-
-
-Similar (but different) drivers
--------------------------------
-
-This driver is NOT the same as the i2c-pport driver found in the i2c
-package. The i2c-pport driver makes use of modern parallel port features so
-that you don't need additional electronics. It has other restrictions
-however, and was not ported to Linux 2.6 (yet).
-
-This driver is also NOT the same as the i2c-pcf-epp driver found in the
-lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as
-an I2C bus directly. Instead, it uses it to control an external I2C bus
-master. That driver was not ported to Linux 2.6 (yet) either.
-
-
-Legacy documentation for Velleman adapter
------------------------------------------
-
-Useful links:
-Velleman http://www.velleman.be/
-Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html
-
-The project has lead to new libs for the Velleman K8000 and K8005:
- LIBK8000 v1.99.1 and LIBK8005 v0.21
-With these libs, you can control the K8000 interface card and the K8005
-stepper motor card with the simple commands which are in the original
-Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
-many more, using /dev/velleman.
- http://home.wanadoo.nl/hihihi/libk8000.htm
- http://home.wanadoo.nl/hihihi/libk8005.htm
- http://struyve.mine.nu:8080/index.php?block=k8000
- http://sourceforge.net/projects/libk8005/
-
-
-One For All JP1 parallel port adapter
--------------------------------------
-
-The JP1 project revolves around a set of remote controls which expose
-the I2C bus their internal configuration EEPROM lives on via a 6 pin
-jumper in the battery compartment. More details can be found at:
-
-http://www.hifi-remote.com/jp1/
-
-Details of the simple parallel port hardware can be found at:
-
-http://www.hifi-remote.com/jp1/hardware.shtml
diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light.rst
similarity index 92%
rename from Documentation/i2c/busses/i2c-parport-light
rename to Documentation/i2c/busses/i2c-parport-light.rst
index 7071b8ba0af4..af85c8dfcd1a 100644
--- a/Documentation/i2c/busses/i2c-parport-light
+++ b/Documentation/i2c/busses/i2c-parport-light.rst
@@ -1,4 +1,6 @@
+===============================
Kernel driver i2c-parport-light
+===============================
Author: Jean Delvare <jdelvare@suse.de>
diff --git a/Documentation/i2c/busses/i2c-parport.rst b/Documentation/i2c/busses/i2c-parport.rst
new file mode 100644
index 000000000000..fae7c7ba9bd1
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-parport.rst
@@ -0,0 +1,190 @@
+=========================
+Kernel driver i2c-parport
+=========================
+
+Author: Jean Delvare <jdelvare@suse.de>
+
+This is a unified driver for several i2c-over-parallel-port adapters,
+such as the ones made by Philips, Velleman or ELV. This driver is
+meant as a replacement for the older, individual drivers:
+
+ * i2c-philips-par
+ * i2c-elv
+ * i2c-velleman
+ * video/i2c-parport
+ (NOT the same as this one, dedicated to home brew teletext adapters)
+
+It currently supports the following devices:
+
+ * (type=0) Philips adapter
+ * (type=1) home brew teletext adapter
+ * (type=2) Velleman K8000 adapter
+ * (type=3) ELV adapter
+ * (type=4) Analog Devices ADM1032 evaluation board
+ * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
+ * (type=6) Barco LPT->DVI (K5800236) adapter
+ * (type=7) One For All JP1 parallel port adapter
+ * (type=8) VCT-jig
+
+These devices use different pinout configurations, so you have to tell
+the driver what you have, using the type module parameter. There is no
+way to autodetect the devices. Support for different pinout configurations
+can be easily added when needed.
+
+Earlier kernels defaulted to type=0 (Philips). But now, if the type
+parameter is missing, the driver will simply fail to initialize.
+
+SMBus alert support is available on adapters which have this line properly
+connected to the parallel port's interrupt pin.
+
+
+Building your own adapter
+-------------------------
+
+If you want to build you own i2c-over-parallel-port adapter, here is
+a sample electronics schema (credits go to Sylvain Munaut)::
+
+ Device PC
+ Side ___________________Vdd (+) Side
+ | | |
+ --- --- ---
+ | | | | | |
+ |R| |R| |R|
+ | | | | | |
+ --- --- ---
+ | | |
+ | | /| |
+ SCL ----------x--------o |-----------x------------------- pin 2
+ | \| | |
+ | | |
+ | |\ | |
+ SDA ----------x----x---| o---x--------------------------- pin 13
+ | |/ |
+ | |
+ | /| |
+ ---------o |----------------x-------------- pin 3
+ \| | |
+ | |
+ --- ---
+ | | | |
+ |R| |R|
+ | | | |
+ --- ---
+ | |
+ ### ###
+ GND GND
+
+Remarks:
+ - This is the exact pinout and electronics used on the Analog Devices
+ evaluation boards.
+ - All inverters::
+
+ /|
+ -o |-
+ \|
+
+ must be 74HC05, they must be open collector output.
+ - All resitors are 10k.
+ - Pins 18-25 of the parallel port connected to GND.
+ - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
+ The ADM1032 evaluation board uses D4-D7. Beware that the amount of
+ current you can draw from the parallel port is limited. Also note that
+ all connected lines MUST BE driven at the same state, else you'll short
+ circuit the output buffers! So plugging the I2C adapter after loading
+ the i2c-parport module might be a good safety since data line state
+ prior to init may be unknown.
+ - This is 5V!
+ - Obviously you cannot read SCL (so it's not really standard-compliant).
+ Pretty easy to add, just copy the SDA part and use another input pin.
+ That would give (ELV compatible pinout)::
+
+
+ Device PC
+ Side ______________________________Vdd (+) Side
+ | | | |
+ --- --- --- ---
+ | | | | | | | |
+ |R| |R| |R| |R|
+ | | | | | | | |
+ --- --- --- ---
+ | | | |
+ | | |\ | |
+ SCL ----------x--------x--| o---x------------------------ pin 15
+ | | |/ |
+ | | |
+ | | /| |
+ | ---o |-------------x-------------- pin 2
+ | \| | |
+ | | |
+ | | |
+ | |\ | |
+ SDA ---------------x---x--| o--------x------------------- pin 10
+ | |/ |
+ | |
+ | /| |
+ ---o |------------------x--------- pin 3
+ \| | |
+ | |
+ --- ---
+ | | | |
+ |R| |R|
+ | | | |
+ --- ---
+ | |
+ ### ###
+ GND GND
+
+
+If possible, you should use the same pinout configuration as existing
+adapters do, so you won't even have to change the code.
+
+
+Similar (but different) drivers
+-------------------------------
+
+This driver is NOT the same as the i2c-pport driver found in the i2c
+package. The i2c-pport driver makes use of modern parallel port features so
+that you don't need additional electronics. It has other restrictions
+however, and was not ported to Linux 2.6 (yet).
+
+This driver is also NOT the same as the i2c-pcf-epp driver found in the
+lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as
+an I2C bus directly. Instead, it uses it to control an external I2C bus
+master. That driver was not ported to Linux 2.6 (yet) either.
+
+
+Legacy documentation for Velleman adapter
+-----------------------------------------
+
+Useful links:
+
+- Velleman http://www.velleman.be/
+- Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html
+
+The project has lead to new libs for the Velleman K8000 and K8005:
+
+ LIBK8000 v1.99.1 and LIBK8005 v0.21
+
+With these libs, you can control the K8000 interface card and the K8005
+stepper motor card with the simple commands which are in the original
+Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
+many more, using /dev/velleman.
+
+ - http://home.wanadoo.nl/hihihi/libk8000.htm
+ - http://home.wanadoo.nl/hihihi/libk8005.htm
+ - http://struyve.mine.nu:8080/index.php?block=k8000
+ - http://sourceforge.net/projects/libk8005/
+
+
+One For All JP1 parallel port adapter
+-------------------------------------
+
+The JP1 project revolves around a set of remote controls which expose
+the I2C bus their internal configuration EEPROM lives on via a 6 pin
+jumper in the battery compartment. More details can be found at:
+
+http://www.hifi-remote.com/jp1/
+
+Details of the simple parallel port hardware can be found at:
+
+http://www.hifi-remote.com/jp1/hardware.shtml
diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa.rst
similarity index 72%
rename from Documentation/i2c/busses/i2c-pca-isa
rename to Documentation/i2c/busses/i2c-pca-isa.rst
index b044e5265488..a254010c8055 100644
--- a/Documentation/i2c/busses/i2c-pca-isa
+++ b/Documentation/i2c/busses/i2c-pca-isa.rst
@@ -1,6 +1,9 @@
+=========================
Kernel driver i2c-pca-isa
+=========================
Supported adapters:
+
This driver supports ISA boards using the Philips PCA 9564
Parallel bus to I2C bus controller
@@ -10,11 +13,11 @@ Module Parameters
-----------------
* base int
- I/O base address
+ I/O base address
* irq int
- IRQ interrupt
+ IRQ interrupt
* clock int
- Clock rate as described in table 1 of PCA9564 datasheet
+ Clock rate as described in table 1 of PCA9564 datasheet
Description
-----------
diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4.rst
similarity index 92%
rename from Documentation/i2c/busses/i2c-piix4
rename to Documentation/i2c/busses/i2c-piix4.rst
index 2703bc3acad0..5d4744842b41 100644
--- a/Documentation/i2c/busses/i2c-piix4
+++ b/Documentation/i2c/busses/i2c-piix4.rst
@@ -1,4 +1,6 @@
+=======================
Kernel driver i2c-piix4
+=======================
Supported adapters:
* Intel 82371AB PIIX4 and PIIX4E
@@ -21,8 +23,8 @@ Supported adapters:
Datasheet: Publicly available at the SMSC website http://www.smsc.com
Authors:
- Frodo Looijaard <frodol@dds.nl>
- Philip Edelbrock <phil@netroedge.com>
+ - Frodo Looijaard <frodol@dds.nl>
+ - Philip Edelbrock <phil@netroedge.com>
Module Parameters
@@ -45,10 +47,10 @@ natively understands SMBus commands and you do not have to worry about
timing problems. The bad news is that non-SMBus devices connected to it can
confuse it mightily. Yes, this is known to happen...
-Do 'lspci -v' and see whether it contains an entry like this:
+Do ``lspci -v`` and see whether it contains an entry like this::
-0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
- Flags: medium devsel, IRQ 9
+ 0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
+ Flags: medium devsel, IRQ 9
Bus and device numbers may differ, but the function number must be
identical (like many PCI devices, the PIIX4 incorporates a number of
@@ -91,7 +93,7 @@ the SMI mode.
device is located at 00:0f.0.
2) Now you just need to change the value in 0xD2 register. Get it first with
command: lspci -xxx -s 00:0f.0
- If the value is 0x3 then you need to change it to 0x1
+ If the value is 0x3 then you need to change it to 0x1:
setpci -s 00:0f.0 d2.b=1
Please note that you don't need to do that in all cases, just when the SMBus is
diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595.rst
similarity index 74%
rename from Documentation/i2c/busses/i2c-sis5595
rename to Documentation/i2c/busses/i2c-sis5595.rst
index ecd21fb49a8f..5614afe35e79 100644
--- a/Documentation/i2c/busses/i2c-sis5595
+++ b/Documentation/i2c/busses/i2c-sis5595.rst
@@ -1,9 +1,11 @@
+=========================
Kernel driver i2c-sis5595
+=========================
Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>,
- Philip Edelbrock <phil@netroedge.com>
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+ - Philip Edelbrock <phil@netroedge.com>
Supported adapters:
* Silicon Integrated Systems Corp. SiS5595 Southbridge
@@ -11,14 +13,19 @@ Supported adapters:
Note: all have mfr. ID 0x1039.
+ ========= ======
SUPPORTED PCI ID
+ ========= ======
5595 0008
+ ========= ======
Note: these chips contain a 0008 device which is incompatible with the
5595. We recognize these by the presence of the listed
"blacklist" PCI ID and refuse to load.
+ ============= ====== ================
NOT SUPPORTED PCI ID BLACKLIST PCI ID
+ ============= ====== ================
540 0008 0540
550 0008 0550
5513 0008 5511
@@ -36,15 +43,18 @@ Note: all have mfr. ID 0x1039.
735 0008 0735
745 0008 0745
746 0008 0746
+ ============= ====== ================
Module Parameters
-----------------
-* force_addr=0xaddr Set the I/O base address. Useful for boards
+================== =====================================================
+force_addr=0xaddr Set the I/O base address. Useful for boards
that don't set the address in the BIOS. Does not do a
PCI force; the device must still be present in lspci.
Don't use this unless the driver complains that the
base address is not set.
+================== =====================================================
Description
-----------
diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630
deleted file mode 100644
index ee7943631074..000000000000
--- a/Documentation/i2c/busses/i2c-sis630
+++ /dev/null
@@ -1,58 +0,0 @@
-Kernel driver i2c-sis630
-
-Supported adapters:
- * Silicon Integrated Systems Corp (SiS)
- 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux)
- 730 chipset
- 964 chipset
- * Possible other SiS chipsets ?
-
-Author: Alexander Malysh <amalysh@web.de>
- Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
-
-Module Parameters
------------------
-
-* force = [1|0] Forcibly enable the SIS630. DANGEROUS!
- This can be interesting for chipsets not named
- above to check if it works for you chipset, but DANGEROUS!
-
-* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
- what your BIOS use). DANGEROUS! This should be a bit
- faster, but freeze some systems (i.e. my Laptop).
- SIS630/730 chip only.
-
-
-Description
------------
-
-This SMBus only driver is known to work on motherboards with the above
-named chipsets.
-
-If you see something like this:
-
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-
-or like this:
-
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-
-or like this:
-
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
- LPC Controller (rev 36)
-
-in your 'lspci' output , then this driver is for your chipset.
-
-Thank You
----------
-Philip Edelbrock <phil@netroedge.com>
-- testing SiS730 support
-Mark M. Hoffman <mhoffman@lightlink.com>
-- bug fixes
-
-To anyone else which I forgot here ;), thanks!
-
diff --git a/Documentation/i2c/busses/i2c-sis630.rst b/Documentation/i2c/busses/i2c-sis630.rst
new file mode 100644
index 000000000000..f37700e885f2
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-sis630.rst
@@ -0,0 +1,64 @@
+========================
+Kernel driver i2c-sis630
+========================
+
+Supported adapters:
+ * Silicon Integrated Systems Corp (SiS)
+ 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux)
+ 730 chipset
+ 964 chipset
+ * Possible other SiS chipsets ?
+
+Author:
+ - Alexander Malysh <amalysh@web.de>
+ - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
+
+Module Parameters
+-----------------
+
+================== =====================================================
+force = [1|0] Forcibly enable the SIS630. DANGEROUS!
+ This can be interesting for chipsets not named
+ above to check if it works for you chipset,
+ but DANGEROUS!
+
+high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
+ what your BIOS use). DANGEROUS! This should be a bit
+ faster, but freeze some systems (i.e. my Laptop).
+ SIS630/730 chip only.
+================== =====================================================
+
+
+Description
+-----------
+
+This SMBus only driver is known to work on motherboards with the above
+named chipsets.
+
+If you see something like this::
+
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
+ 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+
+or like this::
+
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
+ 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+
+or like this::
+
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
+ 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
+ LPC Controller (rev 36)
+
+in your ``lspci`` output , then this driver is for your chipset.
+
+Thank You
+---------
+Philip Edelbrock <phil@netroedge.com>
+- testing SiS730 support
+Mark M. Hoffman <mhoffman@lightlink.com>
+- bug fixes
+
+To anyone else which I forgot here ;), thanks!
+
diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x.rst
similarity index 75%
rename from Documentation/i2c/busses/i2c-sis96x
rename to Documentation/i2c/busses/i2c-sis96x.rst
index 0b979f3252a4..b84581ade213 100644
--- a/Documentation/i2c/busses/i2c-sis96x
+++ b/Documentation/i2c/busses/i2c-sis96x.rst
@@ -1,11 +1,16 @@
+========================
Kernel driver i2c-sis96x
+========================
Replaces 2.4.x i2c-sis645
Supported adapters:
+
* Silicon Integrated Systems Corp (SiS)
+
Any combination of these host bridges:
645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746
+
and these south bridges:
961, 962, 963(L)
@@ -21,17 +26,17 @@ those of the SiS630, although they are located in a completely different
place. Thanks to Alexander Malysh <amalysh@web.de> for providing the
SiS630 datasheet (and driver).
-The command "lspci" as root should produce something like these lines:
+The command ``lspci`` as root should produce something like these lines::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+ 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+ 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
-or perhaps this...
+or perhaps this::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+ 00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
+ 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
(kernel versions later than 2.4.18 may fill in the "Unknown"s)
@@ -50,7 +55,7 @@ TO DOs
------
* The driver does not support SMBus block reads/writes; I may add them if a
-scenario is found where they're needed.
+ scenario is found where they're needed.
Thank You
@@ -58,14 +63,19 @@ Thank You
Mark D. Studebaker <mdsxyz123@yahoo.com>
- design hints and bug fixes
+
Alexander Maylsh <amalysh@web.de>
- ditto, plus an important datasheet... almost the one I really wanted
+
Hans-Günter Lütke Uphues <hg_lu@t-online.de>
- patch for SiS735
+
Robert Zwerus <arzie@dds.nl>
- testing for SiS645DX
+
Kianusch Sayah Karadji <kianusch@sk-tech.net>
- patch for SiS645DX/962
+
Ken Healy
- patch for SiS655
diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm.rst
similarity index 91%
rename from Documentation/i2c/busses/i2c-taos-evm
rename to Documentation/i2c/busses/i2c-taos-evm.rst
index 60299555dcf0..f342e313ee3d 100644
--- a/Documentation/i2c/busses/i2c-taos-evm
+++ b/Documentation/i2c/busses/i2c-taos-evm.rst
@@ -1,4 +1,6 @@
+==========================
Kernel driver i2c-taos-evm
+==========================
Author: Jean Delvare <jdelvare@suse.de>
@@ -23,10 +25,10 @@ Using this driver
In order to use this driver, you'll need the serport driver, and the
inputattach tool, which is part of the input-utils package. The following
commands will tell the kernel that you have a TAOS EVM on the first
-serial port:
+serial port::
-# modprobe serport
-# inputattach --taos-evm /dev/ttyS0
+ # modprobe serport
+ # inputattach --taos-evm /dev/ttyS0
Technical details
diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via.rst
similarity index 61%
rename from Documentation/i2c/busses/i2c-via
rename to Documentation/i2c/busses/i2c-via.rst
index 343870661ac3..df1df5adff7b 100644
--- a/Documentation/i2c/busses/i2c-via
+++ b/Documentation/i2c/busses/i2c-via.rst
@@ -1,4 +1,6 @@
+=====================
Kernel driver i2c-via
+=====================
Supported adapters:
* VIA Technologies, InC. VT82C586B
@@ -15,20 +17,24 @@ The following VIA pci chipsets are supported:
- MVP3, VP3, VP2/97, VPX/97
- others with South bridge VT82C586B
-Your lspci listing must show this :
+Your ``lspci`` listing must show this ::
Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10)
- Problems?
+Problems?
+---------
- Q: You have VT82C586B on the motherboard, but not in the listing.
+ Q:
+ You have VT82C586B on the motherboard, but not in the listing.
- A: Go to your BIOS setup, section PCI devices or similar.
+ A:
+ Go to your BIOS setup, section PCI devices or similar.
Turn USB support on, and try again.
- Q: No error messages, but still i2c doesn't seem to work.
+ Q:
+ No error messages, but still i2c doesn't seem to work.
- A: This can happen. This driver uses the pins VIA recommends in their
+ A:
+ This can happen. This driver uses the pins VIA recommends in their
datasheets, but there are several ways the motherboard manufacturer
can actually wire the lines.
-
diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro.rst
similarity index 87%
rename from Documentation/i2c/busses/i2c-viapro
rename to Documentation/i2c/busses/i2c-viapro.rst
index ab64ce21c254..1762f0cf93d0 100644
--- a/Documentation/i2c/busses/i2c-viapro
+++ b/Documentation/i2c/busses/i2c-viapro.rst
@@ -1,4 +1,6 @@
+========================
Kernel driver i2c-viapro
+========================
Supported adapters:
* VIA Technologies, Inc. VT82C596A/B
@@ -26,9 +28,9 @@ Supported adapters:
Datasheet: available on http://linux.via.com.tw
Authors:
- Kyösti Mälkki <kmalkki@cc.hut.fi>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>,
- Jean Delvare <jdelvare@suse.de>
+ - Kyösti Mälkki <kmalkki@cc.hut.fi>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+ - Jean Delvare <jdelvare@suse.de>
Module Parameters
-----------------
@@ -44,8 +46,9 @@ Description
i2c-viapro is a true SMBus host driver for motherboards with one of the
supported VIA south bridges.
-Your lspci -n listing must show one of these :
+Your ``lspci -n`` listing must show one of these :
+ ================ ======================
device 1106:3050 (VT82C596A function 3)
device 1106:3051 (VT82C596B function 3)
device 1106:3057 (VT82C686 function 4)
@@ -61,6 +64,7 @@ Your lspci -n listing must show one of these :
device 1106:8353 (VX800/VX820)
device 1106:8409 (VX855/VX875)
device 1106:8410 (VX900)
+ ================ ======================
If none of these show up, you should look in the BIOS for settings like
enable ACPI / SMBus or even USB.
diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst
new file mode 100644
index 000000000000..97ca4d510816
--- /dev/null
+++ b/Documentation/i2c/busses/index.rst
@@ -0,0 +1,33 @@
+. SPDX-License-Identifier: GPL-2.0
+
+===============
+I2C Bus Drivers
+===============
+
+.. toctree::
+ :maxdepth: 1
+
+ i2c-ali1535
+ i2c-ali1563
+ i2c-ali15x3
+ i2c-amd756
+ i2c-amd8111
+ i2c-amd-mp2
+ i2c-diolan-u2c
+ i2c-i801
+ i2c-ismt
+ i2c-mlxcpld
+ i2c-nforce2
+ i2c-nvidia-gpu
+ i2c-ocores
+ i2c-parport-light
+ i2c-parport
+ i2c-pca-isa
+ i2c-piix4
+ i2c-sis5595
+ i2c-sis630
+ i2c-sis96x
+ i2c-taos-evm
+ i2c-viapro
+ i2c-via
+ scx200_acb
diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb.rst
similarity index 86%
rename from Documentation/i2c/busses/scx200_acb
rename to Documentation/i2c/busses/scx200_acb.rst
index ce83c871fe95..8dc7c352508c 100644
--- a/Documentation/i2c/busses/scx200_acb
+++ b/Documentation/i2c/busses/scx200_acb.rst
@@ -1,4 +1,6 @@
+========================
Kernel driver scx200_acb
+========================
Author: Christer Weinigel <wingel@nano-system.com>
@@ -25,8 +27,11 @@ Device-specific notes
The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820.
If the scx200_acb driver is built into the kernel, add the following
-parameter to your boot command line:
+parameter to your boot command line::
+
scx200_acb.base=0x810,0x820
+
If the scx200_acb driver is built as a module, add the following line to
-a configuration file in /etc/modprobe.d/ instead:
+a configuration file in /etc/modprobe.d/ instead::
+
options scx200_acb base=0x810,0x820
diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface.rst
similarity index 71%
rename from Documentation/i2c/dev-interface
rename to Documentation/i2c/dev-interface.rst
index fbed645ccd75..69c23a3c2b1b 100644
--- a/Documentation/i2c/dev-interface
+++ b/Documentation/i2c/dev-interface.rst
@@ -1,3 +1,7 @@
+====================
+I2C Device Interface
+====================
+
Usually, i2c devices are controlled by a kernel driver. But it is also
possible to access all devices on an adapter from userspace, through
the /dev interface. You need to load module i2c-dev for this.
@@ -18,7 +22,7 @@ C example
=========
So let's say you want to access an i2c adapter from a C program.
-First, you need to include these two headers:
+First, you need to include these two headers::
#include <linux/i2c-dev.h>
#include <i2c/smbus.h>
@@ -28,7 +32,7 @@ inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
Adapter numbers are assigned somewhat dynamically, so you can not
assume much about them. They can even change from one boot to the next.
-Next thing, open the device file, as follows:
+Next thing, open the device file, as follows::
int file;
int adapter_nr = 2; /* probably dynamically determined */
@@ -42,7 +46,7 @@ Next thing, open the device file, as follows:
}
When you have opened the device, you must specify with what device
-address you want to communicate:
+address you want to communicate::
int addr = 0x40; /* The I2C address */
@@ -53,7 +57,7 @@ address you want to communicate:
Well, you are all set up now. You can now use SMBus commands or plain
I2C to communicate with your device. SMBus commands are preferred if
-the device supports them. Both are illustrated below.
+the device supports them. Both are illustrated below::
__u8 reg = 0x10; /* Device register to access */
__s32 res;
@@ -100,35 +104,35 @@ Full interface description
The following IOCTLs are defined:
-ioctl(file, I2C_SLAVE, long addr)
+``ioctl(file, I2C_SLAVE, long addr)``
Change slave address. The address is passed in the 7 lower bits of the
argument (except for 10 bit addresses, passed in the 10 lower bits in this
case).
-ioctl(file, I2C_TENBIT, long select)
+``ioctl(file, I2C_TENBIT, long select)``
Selects ten bit addresses if select not equals 0, selects normal 7 bit
addresses if select equals 0. Default 0. This request is only valid
if the adapter has I2C_FUNC_10BIT_ADDR.
-ioctl(file, I2C_PEC, long select)
+``ioctl(file, I2C_PEC, long select)``
Selects SMBus PEC (packet error checking) generation and verification
if select not equals 0, disables if select equals 0. Default 0.
Used only for SMBus transactions. This request only has an effect if the
the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just
doesn't have any effect.
-ioctl(file, I2C_FUNCS, unsigned long *funcs)
- Gets the adapter functionality and puts it in *funcs.
+``ioctl(file, I2C_FUNCS, unsigned long *funcs)``
+ Gets the adapter functionality and puts it in ``*funcs``.
-ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
+``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)``
Do combined read/write transaction without stop in between.
Only valid if the adapter has I2C_FUNC_I2C. The argument is
- a pointer to a
+ a pointer to a::
- struct i2c_rdwr_ioctl_data {
+ struct i2c_rdwr_ioctl_data {
struct i2c_msg *msgs; /* ptr to array of simple messages */
int nmsgs; /* number of messages to exchange */
- }
+ }
The msgs[] themselves contain further pointers into data buffers.
The function will write or read data to or from that buffers depending
@@ -136,8 +140,8 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
The slave address and whether to use ten bit address mode has to be
set in each message, overriding the values set with the above ioctl's.
-ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)
- If possible, use the provided i2c_smbus_* methods described below instead
+``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)``
+ If possible, use the provided ``i2c_smbus_*`` methods described below instead
of issuing direct ioctls.
You can do plain i2c transactions by using read(2) and write(2) calls.
@@ -145,7 +149,8 @@ You do not need to pass the address byte; instead, set it through
ioctl I2C_SLAVE before you try to access the device.
You can do SMBus level transactions (see documentation file smbus-protocol
-for details) through the following functions:
+for details) through the following functions::
+
__s32 i2c_smbus_write_quick(int file, __u8 value);
__s32 i2c_smbus_read_byte(int file);
__s32 i2c_smbus_write_byte(int file, __u8 value);
@@ -157,6 +162,7 @@ for details) through the following functions:
__s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
__s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
__u8 *values);
+
All these transactions return -1 on failure; you can read errno to see
what happened. The 'write' transactions return 0 on success; the
'read' transactions return the read value, except for read_block, which
@@ -174,39 +180,39 @@ Implementation details
For the interested, here's the code flow which happens inside the kernel
when you use the /dev interface to I2C:
-1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in
-section "C example" above.
+1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in
+ section "C example" above.
-2* These open() and ioctl() calls are handled by the i2c-dev kernel
-driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
-respectively. You can think of i2c-dev as a generic I2C chip driver
-that can be programmed from user-space.
+2) These open() and ioctl() calls are handled by the i2c-dev kernel
+ driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
+ respectively. You can think of i2c-dev as a generic I2C chip driver
+ that can be programmed from user-space.
-3* Some ioctl() calls are for administrative tasks and are handled by
-i2c-dev directly. Examples include I2C_SLAVE (set the address of the
-device you want to access) and I2C_PEC (enable or disable SMBus error
-checking on future transactions.)
+3) Some ioctl() calls are for administrative tasks and are handled by
+ i2c-dev directly. Examples include I2C_SLAVE (set the address of the
+ device you want to access) and I2C_PEC (enable or disable SMBus error
+ checking on future transactions.)
-4* Other ioctl() calls are converted to in-kernel function calls by
-i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
-functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
-performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
+4) Other ioctl() calls are converted to in-kernel function calls by
+ i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
+ functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
+ performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
-The i2c-dev driver is responsible for checking all the parameters that
-come from user-space for validity. After this point, there is no
-difference between these calls that came from user-space through i2c-dev
-and calls that would have been performed by kernel I2C chip drivers
-directly. This means that I2C bus drivers don't need to implement
-anything special to support access from user-space.
+ The i2c-dev driver is responsible for checking all the parameters that
+ come from user-space for validity. After this point, there is no
+ difference between these calls that came from user-space through i2c-dev
+ and calls that would have been performed by kernel I2C chip drivers
+ directly. This means that I2C bus drivers don't need to implement
+ anything special to support access from user-space.
-5* These i2c.h functions are wrappers to the actual implementation of
-your I2C bus driver. Each adapter must declare callback functions
-implementing these standard calls. i2c.h:i2c_get_functionality() calls
-i2c_adapter.algo->functionality(), while
-i2c-core-smbus.c:i2c_smbus_xfer() calls either
-adapter.algo->smbus_xfer() if it is implemented, or if not,
-i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
-i2c_adapter.algo->master_xfer().
+5) These i2c.h functions are wrappers to the actual implementation of
+ your I2C bus driver. Each adapter must declare callback functions
+ implementing these standard calls. i2c.h:i2c_get_functionality() calls
+ i2c_adapter.algo->functionality(), while
+ i2c-core-smbus.c:i2c_smbus_xfer() calls either
+ adapter.algo->smbus_xfer() if it is implemented, or if not,
+ i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
+ i2c_adapter.algo->master_xfer().
After your I2C bus driver has processed these requests, execution runs
up the call chain, with almost no processing done, except by i2c-dev to
diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/dma-considerations.rst
similarity index 100%
rename from Documentation/i2c/DMA-considerations
rename to Documentation/i2c/dma-considerations.rst
diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes.rst
similarity index 98%
rename from Documentation/i2c/fault-codes
rename to Documentation/i2c/fault-codes.rst
index 0cee0fc545b4..a09797588849 100644
--- a/Documentation/i2c/fault-codes
+++ b/Documentation/i2c/fault-codes.rst
@@ -1,3 +1,7 @@
+=====================
+I2C/SMBUS Fault Codes
+=====================
+
This is a summary of the most important conventions for use of fault
codes in the I2C/SMBus stack.
diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality.rst
similarity index 91%
rename from Documentation/i2c/functionality
rename to Documentation/i2c/functionality.rst
index 4aae8ed15873..7528c1ffd6ca 100644
--- a/Documentation/i2c/functionality
+++ b/Documentation/i2c/functionality.rst
@@ -1,3 +1,7 @@
+=======================
+I2C/SMBus Functionality
+=======================
+
INTRODUCTION
------------
@@ -14,6 +18,7 @@ FUNCTIONALITY CONSTANTS
For the most up-to-date list of functionality constants, please check
<uapi/linux/i2c.h>!
+ =============================== ==============================================
I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus
adapters typically can not do these)
I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions
@@ -33,9 +38,11 @@ For the most up-to-date list of functionality constants, please check
I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command
I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command
I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command
+ =============================== ==============================================
A few combinations of the above flags are also defined for your convenience:
+ ========================= ======================================
I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte
and write_byte commands
I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data
@@ -49,6 +56,7 @@ A few combinations of the above flags are also defined for your convenience:
I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be
emulated by a real I2C adapter (using
the transparent emulation layer)
+ ========================= ======================================
In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as
part of I2C_FUNC_PROTOCOL_MANGLING.
@@ -58,11 +66,11 @@ ADAPTER IMPLEMENTATION
----------------------
When you write a new adapter driver, you will have to implement a
-function callback `functionality'. Typical implementations are given
+function callback ``functionality``. Typical implementations are given
below.
A typical SMBus-only adapter would list all the SMBus transactions it
-supports. This example comes from the i2c-piix4 driver:
+supports. This example comes from the i2c-piix4 driver::
static u32 piix4_func(struct i2c_adapter *adapter)
{
@@ -72,7 +80,7 @@ supports. This example comes from the i2c-piix4 driver:
}
A typical full-I2C adapter would use the following (from the i2c-pxa
-driver):
+driver)::
static u32 i2c_pxa_functionality(struct i2c_adapter *adap)
{
@@ -94,7 +102,7 @@ CLIENT CHECKING
Before a client tries to attach to an adapter, or even do tests to check
whether one of the devices it supports is present on an adapter, it should
check whether the needed functionality is present. The typical way to do
-this is (from the lm75 driver):
+this is (from the lm75 driver)::
static int lm75_detect(...)
{
@@ -129,7 +137,7 @@ If you try to access an adapter from a userspace program, you will have
to use the /dev interface. You will still have to check whether the
functionality you need is supported, of course. This is done using
the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is
-below:
+below::
int file;
if (file = open("/dev/i2c-0", O_RDWR) < 0) {
diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection.rst
similarity index 97%
rename from Documentation/i2c/gpio-fault-injection
rename to Documentation/i2c/gpio-fault-injection.rst
index c87f416d53dd..9dca6ec7d266 100644
--- a/Documentation/i2c/gpio-fault-injection
+++ b/Documentation/i2c/gpio-fault-injection.rst
@@ -104,10 +104,10 @@ There doesn't need to be a device at this address because arbitration lost
should be detected beforehand. Also note, that SCL going down is monitored
using interrupts, so the interrupt latency might cause the first bits to be not
corrupted. A good starting point for using this fault injector on an otherwise
-idle bus is:
+idle bus is::
-# echo 200 > lose_arbitration &
-# i2cget -y <bus_to_test> 0x3f
+ # echo 200 > lose_arbitration &
+ # i2cget -y <bus_to_test> 0x3f
Panic during transfer
=====================
@@ -127,10 +127,10 @@ The calling process will then sleep and wait for the next bus clock. The
process is interruptible, though.
Start of a transfer is detected by waiting for SCL going down by the master
-under test. A good starting point for using this fault injector is:
+under test. A good starting point for using this fault injector is::
-# echo 0 > inject_panic &
-# i2cget -y <bus_to_test> <some_address>
+ # echo 0 > inject_panic &
+ # i2cget -y <bus_to_test> <some_address>
Note that there doesn't need to be a device listening to the address you are
using. Results may vary depending on that, though.
diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol.rst
similarity index 83%
rename from Documentation/i2c/i2c-protocol
rename to Documentation/i2c/i2c-protocol.rst
index ff6d6cee6c7e..2f8fcf671b2e 100644
--- a/Documentation/i2c/i2c-protocol
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -1,8 +1,13 @@
+============
+I2C Protocol
+============
+
This document describes the i2c protocol. Or will, when it is finished :-)
Key to symbols
==============
+=============== =============================================================
S (1 bit) : Start bit
P (1 bit) : Stop bit
Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
@@ -15,33 +20,35 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
for 16 bit data.
Count (8 bits): A data byte containing the length of a block operation.
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
+[..]: Data sent by I2C device, as opposed to data sent by the
+ host adapter.
+=============== =============================================================
Simple send transaction
-======================
+=======================
-This corresponds to i2c_master_send.
+This corresponds to i2c_master_send::
S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
Simple receive transaction
-===========================
+==========================
-This corresponds to i2c_master_recv
+This corresponds to i2c_master_recv::
S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
Combined transactions
-====================
+=====================
This corresponds to i2c_transfer
They are just like the above transactions, but instead of a stop bit P
a start bit S is sent and the transaction continues. An example of
-a byte read, followed by a byte write:
+a byte read, followed by a byte write::
S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
@@ -65,8 +72,10 @@ I2C_M_NO_RD_ACK:
I2C_M_NOSTART:
In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
point. For example, setting I2C_M_NOSTART on the second partial message
- generates something like:
+ generates something like::
+
S Addr Rd [A] [Data] NA Data [A] P
+
If you set the I2C_M_NOSTART variable for the first partial message,
we do not generate Addr, but we do generate the startbit S. This will
probably confuse all other clients on your bus, so don't try this.
@@ -79,7 +88,8 @@ I2C_M_NOSTART:
I2C_M_REV_DIR_ADDR:
This toggles the Rd/Wr flag. That is, if you want to do a write, but
need to emit an Rd instead of a Wr, or vice versa, you set this
- flag. For example:
+ flag. For example::
+
S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
I2C_M_STOP:
diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub.rst
similarity index 93%
rename from Documentation/i2c/i2c-stub
rename to Documentation/i2c/i2c-stub.rst
index a16924fbd289..f8f194dfd379 100644
--- a/Documentation/i2c/i2c-stub
+++ b/Documentation/i2c/i2c-stub.rst
@@ -1,6 +1,9 @@
-MODULE: i2c-stub
+========
+i2c-stub
+========
-DESCRIPTION:
+Description
+===========
This module is a very simple fake I2C/SMBus driver. It implements six
types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w)
@@ -28,6 +31,7 @@ SMBus block operations. Writes can be partial. Block read commands always
return the number of bytes selected with the largest write so far.
The typical use-case is like this:
+
1. load this module
2. use i2cset (from the i2c-tools project) to pre-load some data
3. load the target chip driver module
@@ -36,7 +40,8 @@ The typical use-case is like this:
There's a script named i2c-stub-from-dump in the i2c-tools package which
can load register values automatically from a chip dump.
-PARAMETERS:
+Parameters
+==========
int chip_addr[10]:
The SMBus addresses to emulate chips at.
@@ -47,14 +52,12 @@ unsigned long functionality:
value 0x1f0000 would only enable the quick, byte and byte data
commands.
-u8 bank_reg[10]
-u8 bank_mask[10]
-u8 bank_start[10]
-u8 bank_end[10]:
+u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]:
Optional bank settings. They tell which bits in which register
select the active bank, as well as the range of banked registers.
-CAVEATS:
+Caveats
+=======
If your target driver polls some byte or word waiting for it to change, the
stub could lock it up. Use i2cset to unlock it.
diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology.rst
similarity index 89%
rename from Documentation/i2c/i2c-topology
rename to Documentation/i2c/i2c-topology.rst
index f74d78b53d4d..0c1ae95f6a97 100644
--- a/Documentation/i2c/i2c-topology
+++ b/Documentation/i2c/i2c-topology.rst
@@ -1,3 +1,4 @@
+============
I2C topology
============
@@ -14,6 +15,7 @@ than a straight-forward i2c bus with one adapter and one or more devices.
that has to be operated before the device can be accessed.
Etc
+===
These constructs are represented as i2c adapter trees by Linux, where
each adapter has a parent adapter (except the root adapter) and zero or
@@ -37,7 +39,9 @@ mux-locked or parent-locked muxes. As is evident from below, it can be
useful to know if a mux is mux-locked or if it is parent-locked. The
following list was correct at the time of writing:
-In drivers/i2c/muxes/
+In drivers/i2c/muxes/:
+
+====================== =============================================
i2c-arb-gpio-challenge Parent-locked
i2c-mux-gpio Normally parent-locked, mux-locked iff
all involved gpio pins are controlled by the
@@ -52,18 +56,25 @@ i2c-mux-pinctrl Normally parent-locked, mux-locked iff
all involved pinctrl devices are controlled
by the same i2c root adapter that they mux.
i2c-mux-reg Parent-locked
+====================== =============================================
-In drivers/iio/
+In drivers/iio/:
+
+====================== =============================================
gyro/mpu3050 Mux-locked
imu/inv_mpu6050/ Mux-locked
+====================== =============================================
-In drivers/media/
+In drivers/media/:
+
+======================= =============================================
dvb-frontends/lgdt3306a Mux-locked
dvb-frontends/m88ds3103 Parent-locked
dvb-frontends/rtl2830 Parent-locked
dvb-frontends/rtl2832 Mux-locked
dvb-frontends/si2168 Mux-locked
usb/cx231xx/ Parent-locked
+======================= =============================================
Mux-locked muxes
@@ -78,6 +89,7 @@ full transaction, unrelated i2c transfers may interleave the different
stages of the transaction. This has the benefit that the mux driver
may be easier and cleaner to implement, but it has some caveats.
+==== =====================================================================
ML1. If you build a topology with a mux-locked mux being the parent
of a parent-locked mux, this might break the expectation from the
parent-locked mux that the root adapter is locked during the
@@ -105,11 +117,15 @@ ML4. If any non-i2c operation in the mux driver changes the i2c mux state,
Otherwise garbage may appear on the bus as seen from devices
behind the mux, when an unrelated i2c transfer is in flight during
the non-i2c mux-changing operation.
+==== =====================================================================
Mux-locked Example
------------------
+
+::
+
.----------. .--------.
.--------. | mux- |-----| dev D1 |
| root |--+--| locked | '--------'
@@ -148,6 +164,7 @@ adapter during the transaction are unlocked i2c transfers (using e.g.
__i2c_transfer), or a deadlock will follow. There are a couple of
caveats.
+==== ====================================================================
PL1. If you build a topology with a parent-locked mux being the child
of another mux, this might break a possible assumption from the
child mux that the root adapter is unused between its select op
@@ -161,11 +178,14 @@ PL2. If select/deselect calls out to other subsystems such as gpio,
caused by these subsystems are unlocked. This can be convoluted to
accomplish, maybe even impossible if an acceptably clean solution
is sought.
+==== ====================================================================
Parent-locked Example
---------------------
+::
+
.----------. .--------.
.--------. | parent- |-----| dev D1 |
| root |--+--| locked | '--------'
@@ -177,20 +197,20 @@ Parent-locked Example
When there is an access to D1, this happens:
- 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
- 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
- adapter.
- 7. M1 calls ->deselect, if it has one.
- 8. Same rules as in step 5, but for ->deselect.
- 9. M1 unlocks its parent adapter.
-10. M1 unlocks muxes on its parent.
+ 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
+ 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
+ adapter.
+ 7. M1 calls ->deselect, if it has one.
+ 8. Same rules as in step 5, but for ->deselect.
+ 9. M1 unlocks its parent adapter.
+ 10. M1 unlocks muxes on its parent.
This means that accesses to both D2 and D3 are locked out for the full
@@ -203,7 +223,7 @@ Complex Examples
Parent-locked mux as parent of parent-locked mux
------------------------------------------------
-This is a useful topology, but it can be bad.
+This is a useful topology, but it can be bad::
.----------. .----------. .--------.
.--------. | parent- |-----| parent- |-----| dev D1 |
@@ -227,7 +247,7 @@ through and be seen by the M2 adapter, thus closing M2 prematurely.
Mux-locked mux as parent of mux-locked mux
------------------------------------------
-This is a good topology.
+This is a good topology::
.----------. .----------. .--------.
.--------. | mux- |-----| mux- |-----| dev D1 |
@@ -248,7 +268,7 @@ are still possibly interleaved.
Mux-locked mux as parent of parent-locked mux
---------------------------------------------
-This is probably a bad topology.
+This is probably a bad topology::
.----------. .----------. .--------.
.--------. | mux- |-----| parent- |-----| dev D1 |
@@ -282,7 +302,7 @@ auto-closing, the topology is fine.
Parent-locked mux as parent of mux-locked mux
---------------------------------------------
-This is a good topology.
+This is a good topology::
.----------. .----------. .--------.
.--------. | parent- |-----| mux- |-----| dev D1 |
@@ -306,7 +326,7 @@ adapter is locked directly.
Two mux-locked sibling muxes
----------------------------
-This is a good topology.
+This is a good topology::
.--------.
.----------. .--| dev D1 |
@@ -330,7 +350,7 @@ accesses to D5 may be interleaved at any time.
Two parent-locked sibling muxes
-------------------------------
-This is a good topology.
+This is a good topology::
.--------.
.----------. .--| dev D1 |
@@ -354,7 +374,7 @@ out.
Mux-locked and parent-locked sibling muxes
------------------------------------------
-This is a good topology.
+This is a good topology::
.--------.
.----------. .--| dev D1 |
diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
new file mode 100644
index 000000000000..d4ba671d0b55
--- /dev/null
+++ b/Documentation/i2c/index.rst
@@ -0,0 +1,38 @@
+. SPDX-License-Identifier: GPL-2.0
+
+===================
+I2C/SMBus Subsystem
+===================
+
+.. toctree::
+ :maxdepth: 1
+
+ dev-interface
+ dma-considerations
+ fault-codes
+ functionality
+ gpio-fault-injection
+ i2c-protocol
+ i2c-stub
+ i2c-topology
+ instantiating-devices
+ old-module-parameters
+ slave-eeprom-backend
+ slave-interface
+ smbus-protocol
+ summary
+ ten-bit-addresses
+ upgrading-clients
+ writing-clients
+
+ muxes/i2c-mux-gpio
+
+ busses/index
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
+
diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices.rst
similarity index 93%
rename from Documentation/i2c/instantiating-devices
rename to Documentation/i2c/instantiating-devices.rst
index 345e9ea8281a..1238f1fa3382 100644
--- a/Documentation/i2c/instantiating-devices
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -1,3 +1,4 @@
+==============================
How to instantiate I2C devices
==============================
@@ -17,9 +18,9 @@ which is known in advance. It is thus possible to pre-declare the I2C
devices which live on this bus. This is done with an array of struct
i2c_board_info which is registered by calling i2c_register_board_info().
-Example (from omap2 h4):
+Example (from omap2 h4)::
-static struct i2c_board_info h4_i2c_board_info[] __initdata = {
+ static struct i2c_board_info h4_i2c_board_info[] __initdata = {
{
I2C_BOARD_INFO("isp1301_omap", 0x2d),
.irq = OMAP_GPIO_IRQ(125),
@@ -32,15 +33,15 @@ static struct i2c_board_info h4_i2c_board_info[] __initdata = {
I2C_BOARD_INFO("24c01", 0x57),
.platform_data = &m24c01,
},
-};
+ };
-static void __init omap_h4_init(void)
-{
+ static void __init omap_h4_init(void)
+ {
(...)
i2c_register_board_info(1, h4_i2c_board_info,
ARRAY_SIZE(h4_i2c_board_info));
(...)
-}
+ }
The above code declares 3 devices on I2C bus 1, including their respective
addresses and custom data needed by their drivers. When the I2C bus in
@@ -57,7 +58,7 @@ Method 1b: Declare the I2C devices via devicetree
This method has the same implications as method 1a. The declaration of I2C
devices is here done via devicetree as subnodes of the master controller.
-Example:
+Example::
i2c1: i2c@400a0000 {
/* ... master properties skipped ... */
@@ -99,20 +100,20 @@ bus in advance, so the method 1 described above can't be used. Instead,
you can instantiate your I2C devices explicitly. This is done by filling
a struct i2c_board_info and calling i2c_new_device().
-Example (from the sfe4001 network driver):
+Example (from the sfe4001 network driver)::
-static struct i2c_board_info sfe4001_hwmon_info = {
+ static struct i2c_board_info sfe4001_hwmon_info = {
I2C_BOARD_INFO("max6647", 0x4e),
-};
+ };
-int sfe4001_init(struct efx_nic *efx)
-{
+ int sfe4001_init(struct efx_nic *efx)
+ {
(...)
efx->board_info.hwmon_client =
i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info);
(...)
-}
+ }
The above code instantiates 1 I2C device on the I2C bus which is on the
network adapter in question.
@@ -124,12 +125,12 @@ it may have different addresses from one board to the next (manufacturer
changing its design without notice). In this case, you can call
i2c_new_probed_device() instead of i2c_new_device().
-Example (from the nxp OHCI driver):
+Example (from the nxp OHCI driver)::
-static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
+ static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
-static int usb_hcd_nxp_probe(struct platform_device *pdev)
-{
+ static int usb_hcd_nxp_probe(struct platform_device *pdev)
+ {
(...)
struct i2c_adapter *i2c_adap;
struct i2c_board_info i2c_info;
@@ -142,7 +143,7 @@ static int usb_hcd_nxp_probe(struct platform_device *pdev)
normal_i2c, NULL);
i2c_put_adapter(i2c_adap);
(...)
-}
+ }
The above code instantiates up to 1 I2C device on the I2C bus which is on
the OHCI adapter in question. It first tries at address 0x2c, if nothing
@@ -172,6 +173,7 @@ explicitly. Instead, i2c-core will probe for such devices as soon as their
drivers are loaded, and if any is found, an I2C device will be
instantiated automatically. In order to prevent any misbehavior of this
mechanism, the following restrictions apply:
+
* The I2C device driver must implement the detect() method, which
identifies a supported device by reading from arbitrary registers.
* Only buses which are likely to have a supported device and agree to be
@@ -189,6 +191,7 @@ first.
Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6
kernels will find out that this method 3 is essentially similar to what
was done there. Two significant differences are:
+
* Probing is only one way to instantiate I2C devices now, while it was the
only way back then. Where possible, methods 1 and 2 should be preferred.
Method 3 should only be used when there is no other way, as it can have
@@ -224,11 +227,13 @@ device. As no two devices can live at the same address on a given I2C
segment, the address is sufficient to uniquely identify the device to be
deleted.
-Example:
-# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
+Example::
+
+ # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
While this interface should only be used when in-kernel device declaration
can't be done, there is a variety of cases where it can be helpful:
+
* The I2C driver usually detects devices (method 3 above) but the bus
segment your device lives on doesn't have the proper class bit set and
thus detection doesn't trigger.
diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio.rst
similarity index 85%
rename from Documentation/i2c/muxes/i2c-mux-gpio
rename to Documentation/i2c/muxes/i2c-mux-gpio.rst
index 893ecdfe6e43..7d27444035c3 100644
--- a/Documentation/i2c/muxes/i2c-mux-gpio
+++ b/Documentation/i2c/muxes/i2c-mux-gpio.rst
@@ -1,4 +1,6 @@
+==========================
Kernel driver i2c-mux-gpio
+==========================
Author: Peter Korsgaard <peter.korsgaard@barco.com>
@@ -8,7 +10,7 @@ Description
i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments
from a master I2C bus and a hardware MUX controlled through GPIO pins.
-E.G.:
+E.G.::
---------- ---------- Bus segment 1 - - - - -
| | SCL/SDA | |-------------- | |
@@ -33,20 +35,20 @@ bus, the number of bus segments to create and the GPIO pins used
to control it. See include/linux/platform_data/i2c-mux-gpio.h for details.
E.G. something like this for a MUX providing 4 bus segments
-controlled through 3 GPIO pins:
+controlled through 3 GPIO pins::
-#include <linux/platform_data/i2c-mux-gpio.h>
-#include <linux/platform_device.h>
+ #include <linux/platform_data/i2c-mux-gpio.h>
+ #include <linux/platform_device.h>
-static const unsigned myboard_gpiomux_gpios[] = {
+ static const unsigned myboard_gpiomux_gpios[] = {
AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24
-};
+ };
-static const unsigned myboard_gpiomux_values[] = {
+ static const unsigned myboard_gpiomux_values[] = {
0, 1, 2, 3
-};
+ };
-static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
+ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
.parent = 1,
.base_nr = 2, /* optional */
.values = myboard_gpiomux_values,
@@ -54,15 +56,15 @@ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
.gpios = myboard_gpiomux_gpios,
.n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios),
.idle = 4, /* optional */
-};
+ };
-static struct platform_device myboard_i2cmux = {
+ static struct platform_device myboard_i2cmux = {
.name = "i2c-mux-gpio",
.id = 0,
.dev = {
.platform_data = &myboard_i2cmux_data,
},
-};
+ };
If you don't know the absolute GPIO pin numbers at registration time,
you can instead provide a chip name (.chip_name) and relative GPIO pin
diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters.rst
similarity index 75%
rename from Documentation/i2c/old-module-parameters
rename to Documentation/i2c/old-module-parameters.rst
index 8e2b629d533c..a1939512ad66 100644
--- a/Documentation/i2c/old-module-parameters
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -1,3 +1,4 @@
+=================================================
I2C device driver binding control from user-space
=================================================
@@ -19,23 +20,27 @@ Below is a mapping from the old module parameters to the new interface.
Attaching a driver to an I2C device
-----------------------------------
-Old method (module parameters):
-# modprobe <driver> probe=1,0x2d
-# modprobe <driver> force=1,0x2d
-# modprobe <driver> force_<device>=1,0x2d
+Old method (module parameters)::
-New method (sysfs interface):
-# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
+ # modprobe <driver> probe=1,0x2d
+ # modprobe <driver> force=1,0x2d
+ # modprobe <driver> force_<device>=1,0x2d
+
+New method (sysfs interface)::
+
+ # echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
Preventing a driver from attaching to an I2C device
---------------------------------------------------
-Old method (module parameters):
-# modprobe <driver> ignore=1,0x2f
+Old method (module parameters)::
-New method (sysfs interface):
-# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
-# modprobe <driver>
+ # modprobe <driver> ignore=1,0x2f
+
+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
the driver. The dummy device will be handled by i2c-core itself, preventing
diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend.rst
similarity index 90%
rename from Documentation/i2c/slave-eeprom-backend
rename to Documentation/i2c/slave-eeprom-backend.rst
index 04f8d8a9b817..2018fa74c6f3 100644
--- a/Documentation/i2c/slave-eeprom-backend
+++ b/Documentation/i2c/slave-eeprom-backend.rst
@@ -1,3 +1,4 @@
+==============================
Linux I2C slave eeprom backend
==============================
@@ -5,7 +6,7 @@ by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
This is a proof-of-concept backend which acts like an EEPROM on the connected
I2C bus. The memory contents can be modified from userspace via this file
-located in sysfs:
+located in sysfs::
/sys/bus/i2c/devices/<device-directory>/slave-eeprom
diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface.rst
similarity index 94%
rename from Documentation/i2c/slave-interface
rename to Documentation/i2c/slave-interface.rst
index 7e2a228f21bc..9ac5f110a4ec 100644
--- a/Documentation/i2c/slave-interface
+++ b/Documentation/i2c/slave-interface.rst
@@ -1,3 +1,4 @@
+=====================================
Linux I2C slave interface description
=====================================
@@ -12,7 +13,7 @@ EEPROM, the Linux I2C slave can access the content via sysfs and handle data as
needed. The backend driver and the I2C bus driver communicate via events. Here
is a small graph visualizing the data flow and the means by which data is
transported. The dotted line marks only one example. The backend could also
-use a character device, be in-kernel only, or something completely different:
+use a character device, be in-kernel only, or something completely different::
e.g. sysfs I2C slave events I/O registers
@@ -35,7 +36,7 @@ them as described in the document 'instantiating-devices'. The only difference
is that i2c slave backends have their own address space. So, you have to add
0x1000 to the address you would originally request. An example for
instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64
-on bus 1:
+on bus 1::
# echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device
@@ -54,7 +55,7 @@ drivers and writing backends will be given.
I2C slave events
----------------
-The bus driver sends an event to the backend using the following function:
+The bus driver sends an event to the backend using the following function::
ret = i2c_slave_event(client, event, &val)
@@ -69,8 +70,9 @@ Event types:
* I2C_SLAVE_WRITE_REQUESTED (mandatory)
-'val': unused
-'ret': always 0
+ 'val': unused
+
+ 'ret': always 0
Another I2C master wants to write data to us. This event should be sent once
our own address and the write bit was detected. The data did not arrive yet, so
@@ -79,8 +81,9 @@ to be done, though.
* I2C_SLAVE_READ_REQUESTED (mandatory)
-'val': backend returns first byte to be sent
-'ret': always 0
+ 'val': backend returns first byte to be sent
+
+ 'ret': always 0
Another I2C master wants to read data from us. This event should be sent once
our own address and the read bit was detected. After returning, the bus driver
@@ -88,8 +91,9 @@ should transmit the first byte.
* I2C_SLAVE_WRITE_RECEIVED (mandatory)
-'val': bus driver delivers received byte
-'ret': 0 if the byte should be acked, some errno if the byte should be nacked
+ 'val': bus driver delivers received byte
+
+ 'ret': 0 if the byte should be acked, some errno if the byte should be nacked
Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
@@ -97,8 +101,9 @@ should be nacked.
* I2C_SLAVE_READ_PROCESSED (mandatory)
-'val': backend returns next byte to be sent
-'ret': always 0
+ 'val': backend returns next byte to be sent
+
+ 'ret': always 0
The bus driver requests the next byte to be sent to another I2C master in
'val'. Important: This does not mean that the previous byte has been acked, it
@@ -111,8 +116,9 @@ your backend, though.
* I2C_SLAVE_STOP (mandatory)
-'val': unused
-'ret': always 0
+ 'val': unused
+
+ 'ret': always 0
A stop condition was received. This can happen anytime and the backend should
reset its state machine for I2C transfers to be able to receive new requests.
diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol.rst
similarity index 84%
rename from Documentation/i2c/smbus-protocol
rename to Documentation/i2c/smbus-protocol.rst
index 092d474f5843..c6f189bfe1c7 100644
--- a/Documentation/i2c/smbus-protocol
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -1,3 +1,4 @@
+======================
SMBus Protocol Summary
======================
@@ -27,12 +28,13 @@ Each transaction type corresponds to a functionality flag. Before calling a
transaction function, a device driver should always check (just once) for
the corresponding functionality flag to ensure that the underlying I2C
adapter supports the transaction in question. See
-<file:Documentation/i2c/functionality> for the details.
+<file:Documentation/i2c/functionality.rst> for the details.
Key to symbols
==============
+=============== =============================================================
S (1 bit) : Start bit
P (1 bit) : Stop bit
Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
@@ -45,15 +47,17 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
for 16 bit data.
Count (8 bits): A data byte containing the length of a block operation.
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
+[..]: Data sent by I2C device, as opposed to data sent by the host
+ adapter.
+=============== =============================================================
SMBus Quick Command
===================
-This sends a single bit to the device, at the place of the Rd/Wr bit.
+This sends a single bit to the device, at the place of the Rd/Wr bit::
-A Addr Rd/Wr [A] P
+ A Addr Rd/Wr [A] P
Functionality flag: I2C_FUNC_SMBUS_QUICK
@@ -64,9 +68,9 @@ SMBus Receive Byte: i2c_smbus_read_byte()
This reads a single byte from a device, without specifying a device
register. Some devices are so simple that this interface is enough; for
others, it is a shorthand if you want to read the same register as in
-the previous SMBus command.
+the previous SMBus command::
-S Addr Rd [A] [Data] NA P
+ S Addr Rd [A] [Data] NA P
Functionality flag: I2C_FUNC_SMBUS_READ_BYTE
@@ -77,7 +81,9 @@ SMBus Send Byte: i2c_smbus_write_byte()
This operation is the reverse of Receive Byte: it sends a single byte
to a device. See Receive Byte for more information.
-S Addr Wr [A] Data [A] P
+::
+
+ S Addr Wr [A] Data [A] P
Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE
@@ -86,9 +92,9 @@ SMBus Read Byte: i2c_smbus_read_byte_data()
============================================
This reads a single byte from a device, from a designated register.
-The register is specified through the Comm byte.
+The register is specified through the Comm byte::
-S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
+ S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA
@@ -98,9 +104,9 @@ SMBus Read Word: i2c_smbus_read_word_data()
This operation is very like Read Byte; again, data is read from a
device, from a designated register that is specified through the Comm
-byte. But this time, the data is a complete word (16 bits).
+byte. But this time, the data is a complete word (16 bits)::
-S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
+ S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA
@@ -116,7 +122,9 @@ This writes a single byte to a device, to a designated register. The
register is specified through the Comm byte. This is the opposite of
the Read Byte operation.
-S Addr Wr [A] Comm [A] Data [A] P
+::
+
+ S Addr Wr [A] Comm [A] Data [A] P
Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA
@@ -126,9 +134,9 @@ SMBus Write Word: i2c_smbus_write_word_data()
This is the opposite of the Read Word operation. 16 bits
of data is written to a device, to the designated register that is
-specified through the Comm byte.
+specified through the Comm byte.::
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
+ S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA
@@ -141,10 +149,10 @@ SMBus Process Call:
===================
This command selects a device register (through the Comm byte), sends
-16 bits of data to it, and reads 16 bits of data in return.
+16 bits of data to it, and reads 16 bits of data in return::
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
- S Addr Rd [A] [DataLow] A [DataHigh] NA P
+ S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
+ S Addr Rd [A] [DataLow] A [DataHigh] NA P
Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
@@ -156,8 +164,10 @@ This command reads a block of up to 32 bytes from a device, from a
designated register that is specified through the Comm byte. The amount
of data is specified by the device in the Count byte.
-S Addr Wr [A] Comm [A]
- S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
+::
+
+ S Addr Wr [A] Comm [A]
+ S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
@@ -169,7 +179,9 @@ The opposite of the Block Read command, this writes up to 32 bytes to
a device, to a designated register that is specified through the
Comm byte. The amount of data is specified in the Count byte.
-S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
+::
+
+ S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA
@@ -181,10 +193,10 @@ SMBus Block Write - Block Read Process Call was introduced in
Revision 2.0 of the specification.
This command selects a device register (through the Comm byte), sends
-1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return.
+1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return::
-S Addr Wr [A] Comm [A] Count [A] Data [A] ...
- S Addr Rd [A] [Count] A [Data] ... A P
+ S Addr Wr [A] Comm [A] Count [A] Data [A] ...
+ S Addr Rd [A] [Count] A [Data] ... A P
Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL
@@ -197,9 +209,12 @@ SMBus host acting as a slave.
It is the same form as Write Word, with the command code replaced by the
alerting device's address.
-[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
+::
+
+ [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
This is implemented in the following way in the Linux kernel:
+
* I2C bus drivers which support SMBus Host Notify should report
I2C_FUNC_SMBUS_HOST_NOTIFY.
* I2C bus drivers trigger SMBus Host Notify by a call to
@@ -241,6 +256,7 @@ single interrupt pin on the SMBus master, while still allowing the master
to know which slave triggered the interrupt.
This is implemented the following way in the Linux kernel:
+
* I2C bus drivers which support SMBus alert should call
i2c_setup_smbus_alert() to setup SMBus alert support.
* I2C drivers for devices which can trigger SMBus alerts should implement
@@ -262,10 +278,10 @@ I2C Block Read: i2c_smbus_read_i2c_block_data()
================================================
This command reads a block of bytes from a device, from a
-designated register that is specified through the Comm byte.
+designated register that is specified through the Comm byte::
-S Addr Wr [A] Comm [A]
- S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
+ S Addr Wr [A] Comm [A]
+ S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
@@ -278,6 +294,8 @@ a device, to a designated register that is specified through the
Comm byte. Note that command lengths of 0, 2, or more bytes are
supported as they are indistinguishable from data.
-S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
+::
+
+ S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK
diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary.rst
similarity index 96%
rename from Documentation/i2c/summary
rename to Documentation/i2c/summary.rst
index 809541ab352f..8c08fa727f4e 100644
--- a/Documentation/i2c/summary
+++ b/Documentation/i2c/summary.rst
@@ -1,3 +1,4 @@
+=============
I2C and SMBus
=============
@@ -24,7 +25,8 @@ implement all the common SMBus protocol semantics or messages.
Terminology
===========
-When we talk about I2C, we use the following terms:
+When we talk about I2C, we use the following terms::
+
Bus -> Algorithm
Adapter
Device -> Driver
diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses.rst
similarity index 95%
rename from Documentation/i2c/ten-bit-addresses
rename to Documentation/i2c/ten-bit-addresses.rst
index 7b2d11e53a49..5c765aff16d5 100644
--- a/Documentation/i2c/ten-bit-addresses
+++ b/Documentation/i2c/ten-bit-addresses.rst
@@ -1,3 +1,7 @@
+=====================
+I2C Ten-bit Addresses
+=====================
+
The I2C protocol knows about two kinds of device addresses: normal 7 bit
addresses, and an extended set of 10 bit addresses. The sets of addresses
do not intersect: the 7 bit address 0x10 is not the same as the 10 bit
@@ -12,6 +16,7 @@ See the I2C specification for the details.
The current 10 bit address support is minimal. It should work, however
you can expect some problems along the way:
+
* Not all bus drivers support 10-bit addresses. Some don't because the
hardware doesn't support them (SMBus doesn't require 10-bit address
support for example), some don't because nobody bothered adding the
diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients.rst
similarity index 56%
rename from Documentation/i2c/upgrading-clients
rename to Documentation/i2c/upgrading-clients.rst
index 96392cc5b5c7..4a575e607ff8 100644
--- a/Documentation/i2c/upgrading-clients
+++ b/Documentation/i2c/upgrading-clients.rst
@@ -1,3 +1,4 @@
+=================================================
Upgrading I2C Drivers to the new 2.6 Driver Model
=================================================
@@ -13,21 +14,22 @@ the old to the new new binding methods.
Example old-style driver
------------------------
+::
-struct example_state {
+ struct example_state {
struct i2c_client client;
....
-};
+ };
-static struct i2c_driver example_driver;
+ static struct i2c_driver example_driver;
-static unsigned short ignore[] = { I2C_CLIENT_END };
-static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+ static unsigned short ignore[] = { I2C_CLIENT_END };
+ static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
-I2C_CLIENT_INSMOD;
+ I2C_CLIENT_INSMOD;
-static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-{
+ static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+ {
struct example_state *state;
struct device *dev = &adap->dev; /* to use for dev_ reports */
int ret;
@@ -59,23 +61,23 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind)
dev_info(dev, "example client created\n");
return 0;
-}
+ }
-static int example_detach(struct i2c_client *client)
-{
+ static int example_detach(struct i2c_client *client)
+ {
struct example_state *state = i2c_get_clientdata(client);
i2c_detach_client(client);
kfree(state);
return 0;
-}
+ }
-static int example_attach_adapter(struct i2c_adapter *adap)
-{
+ static int example_attach_adapter(struct i2c_adapter *adap)
+ {
return i2c_probe(adap, &addr_data, example_attach);
-}
+ }
-static struct i2c_driver example_driver = {
+ static struct i2c_driver example_driver = {
.driver = {
.owner = THIS_MODULE,
.name = "example",
@@ -83,7 +85,7 @@ static struct i2c_driver example_driver = {
},
.attach_adapter = example_attach_adapter,
.detach_client = example_detach,
-};
+ };
Updating the client
@@ -93,38 +95,38 @@ The new style binding model will check against a list of supported
devices and their associated address supplied by the code registering
the busses. This means that the driver .attach_adapter and
.detach_client methods can be removed, along with the addr_data,
-as follows:
+as follows::
-- static struct i2c_driver example_driver;
+ - static struct i2c_driver example_driver;
-- static unsigned short ignore[] = { I2C_CLIENT_END };
-- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+ - static unsigned short ignore[] = { I2C_CLIENT_END };
+ - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
-- I2C_CLIENT_INSMOD;
+ - I2C_CLIENT_INSMOD;
-- static int example_attach_adapter(struct i2c_adapter *adap)
-- {
-- return i2c_probe(adap, &addr_data, example_attach);
-- }
+ - static int example_attach_adapter(struct i2c_adapter *adap)
+ - {
+ - return i2c_probe(adap, &addr_data, example_attach);
+ - }
- static struct i2c_driver example_driver = {
-- .attach_adapter = example_attach_adapter,
-- .detach_client = example_detach,
- }
+ static struct i2c_driver example_driver = {
+ - .attach_adapter = example_attach_adapter,
+ - .detach_client = example_detach,
+ }
-Add the probe and remove methods to the i2c_driver, as so:
+Add the probe and remove methods to the i2c_driver, as so::
- static struct i2c_driver example_driver = {
-+ .probe = example_probe,
-+ .remove = example_remove,
- }
+ static struct i2c_driver example_driver = {
+ + .probe = example_probe,
+ + .remove = example_remove,
+ }
Change the example_attach method to accept the new parameters
-which include the i2c_client that it will be working with:
+which include the i2c_client that it will be working with::
-- static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-+ static int example_probe(struct i2c_client *client,
-+ const struct i2c_device_id *id)
+ - static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+ + static int example_probe(struct i2c_client *client,
+ + const struct i2c_device_id *id)
Change the name of example_attach to example_probe to align it with the
i2c_driver entry names. The rest of the probe routine will now need to be
@@ -132,55 +134,57 @@ changed as the i2c_client has already been setup for use.
The necessary client fields have already been setup before
the probe function is called, so the following client setup
-can be removed:
+can be removed::
-- example->client.addr = addr;
-- example->client.flags = 0;
-- example->client.adapter = adap;
--
-- strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
+ - example->client.addr = addr;
+ - example->client.flags = 0;
+ - example->client.adapter = adap;
+ -
+ - strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
-The i2c_set_clientdata is now:
+The i2c_set_clientdata is now::
-- i2c_set_clientdata(&state->client, state);
-+ i2c_set_clientdata(client, state);
+ - i2c_set_clientdata(&state->client, state);
+ + i2c_set_clientdata(client, state);
The call to i2c_attach_client is no longer needed, if the probe
routine exits successfully, then the driver will be automatically
-attached by the core. Change the probe routine as so:
+attached by the core. Change the probe routine as so::
-- ret = i2c_attach_client(&state->i2c_client);
-- if (ret < 0) {
-- dev_err(dev, "failed to attach client\n");
-- kfree(state);
-- return ret;
-- }
+ - ret = i2c_attach_client(&state->i2c_client);
+ - if (ret < 0) {
+ - dev_err(dev, "failed to attach client\n");
+ - kfree(state);
+ - return ret;
+ - }
Remove the storage of 'struct i2c_client' from the 'struct example_state'
as we are provided with the i2c_client in our example_probe. Instead we
store a pointer to it for when it is needed.
-struct example_state {
-- struct i2c_client client;
-+ struct i2c_client *client;
+::
-the new i2c client as so:
+ struct example_state {
+ - struct i2c_client client;
+ + struct i2c_client *client;
-- struct device *dev = &adap->dev; /* to use for dev_ reports */
-+ struct device *dev = &i2c_client->dev; /* to use for dev_ reports */
+the new i2c client as so::
+
+ - struct device *dev = &adap->dev; /* to use for dev_ reports */
+ + struct device *dev = &i2c_client->dev; /* to use for dev_ reports */
And remove the change after our client is attached, as the driver no
-longer needs to register a new client structure with the core:
+longer needs to register a new client structure with the core::
-- dev = &state->i2c_client.dev;
+ - dev = &state->i2c_client.dev;
In the probe routine, ensure that the new state has the client stored
-in it:
+in it::
-static int example_probe(struct i2c_client *i2c_client,
+ static int example_probe(struct i2c_client *i2c_client,
const struct i2c_device_id *id)
-{
+ {
struct example_state *state;
struct device *dev = &i2c_client->dev;
int ret;
@@ -191,48 +195,50 @@ static int example_probe(struct i2c_client *i2c_client,
return -ENOMEM;
}
-+ state->client = i2c_client;
+ + state->client = i2c_client;
Update the detach method, by changing the name to _remove and
to delete the i2c_detach_client call. It is possible that you
can also remove the ret variable as it is not needed for any
of the core functions.
-- static int example_detach(struct i2c_client *client)
-+ static int example_remove(struct i2c_client *client)
-{
+::
+
+ - static int example_detach(struct i2c_client *client)
+ + static int example_remove(struct i2c_client *client)
+ {
struct example_state *state = i2c_get_clientdata(client);
-- i2c_detach_client(client);
+ - i2c_detach_client(client);
And finally ensure that we have the correct ID table for the i2c-core
-and other utilities:
+and other utilities::
-+ struct i2c_device_id example_idtable[] = {
-+ { "example", 0 },
-+ { }
-+};
-+
-+MODULE_DEVICE_TABLE(i2c, example_idtable);
+ + struct i2c_device_id example_idtable[] = {
+ + { "example", 0 },
+ + { }
+ +};
+ +
+ +MODULE_DEVICE_TABLE(i2c, example_idtable);
-static struct i2c_driver example_driver = {
+ static struct i2c_driver example_driver = {
.driver = {
.owner = THIS_MODULE,
.name = "example",
},
-+ .id_table = example_ids,
+ + .id_table = example_ids,
-Our driver should now look like this:
+Our driver should now look like this::
-struct example_state {
+ struct example_state {
struct i2c_client *client;
....
-};
+ };
-static int example_probe(struct i2c_client *client,
+ static int example_probe(struct i2c_client *client,
const struct i2c_device_id *id)
-{
+ {
struct example_state *state;
struct device *dev = &client->dev;
@@ -250,24 +256,24 @@ static int example_probe(struct i2c_client *client,
dev_info(dev, "example client created\n");
return 0;
-}
+ }
-static int example_remove(struct i2c_client *client)
-{
+ static int example_remove(struct i2c_client *client)
+ {
struct example_state *state = i2c_get_clientdata(client);
kfree(state);
return 0;
-}
+ }
-static struct i2c_device_id example_idtable[] = {
+ static struct i2c_device_id example_idtable[] = {
{ "example", 0 },
{ }
-};
+ };
-MODULE_DEVICE_TABLE(i2c, example_idtable);
+ MODULE_DEVICE_TABLE(i2c, example_idtable);
-static struct i2c_driver example_driver = {
+ static struct i2c_driver example_driver = {
.driver = {
.owner = THIS_MODULE,
.name = "example",
@@ -276,4 +282,4 @@ static struct i2c_driver example_driver = {
.id_table = example_idtable,
.probe = example_probe,
.remove = example_remove,
-};
+ };
diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients.rst
similarity index 91%
rename from Documentation/i2c/writing-clients
rename to Documentation/i2c/writing-clients.rst
index a755b141fa4a..dddf0a14ab7c 100644
--- a/Documentation/i2c/writing-clients
+++ b/Documentation/i2c/writing-clients.rst
@@ -1,3 +1,7 @@
+===================
+Writing I2C Clients
+===================
+
This is a small guide for those who want to write kernel drivers for I2C
or SMBus devices, using Linux as the protocol host/master (not slave).
@@ -12,7 +16,7 @@ General remarks
Try to keep the kernel namespace as clean as possible. The best way to
do this is to use a unique prefix for all global symbols. This is
especially important for exported symbols, but it is a good idea to do
-it for non-exported symbols too. We will use the prefix `foo_' in this
+it for non-exported symbols too. We will use the prefix ``foo_`` in this
tutorial.
@@ -25,15 +29,17 @@ routines, and should be zero-initialized except for fields with data you
provide. A client structure holds device-specific information like the
driver model device node, and its I2C address.
-static struct i2c_device_id foo_idtable[] = {
+::
+
+ static struct i2c_device_id foo_idtable[] = {
{ "foo", my_id_for_foo },
{ "bar", my_id_for_bar },
{ }
-};
+ };
-MODULE_DEVICE_TABLE(i2c, foo_idtable);
+ MODULE_DEVICE_TABLE(i2c, foo_idtable);
-static struct i2c_driver foo_driver = {
+ static struct i2c_driver foo_driver = {
.driver = {
.name = "foo",
.pm = &foo_pm_ops, /* optional */
@@ -49,7 +55,7 @@ static struct i2c_driver foo_driver = {
.shutdown = foo_shutdown, /* optional */
.command = foo_command, /* optional, deprecated */
-}
+ }
The name field is the driver name, and must not contain spaces. It
should match the module name (if the driver can be compiled as a module),
@@ -64,16 +70,18 @@ below.
Extra client data
=================
-Each client structure has a special `data' field that can point to any
+Each client structure has a special ``data`` field that can point to any
structure at all. You should use this to keep device-specific data.
+::
+
/* store the value */
void i2c_set_clientdata(struct i2c_client *client, void *data);
/* retrieve the value */
void *i2c_get_clientdata(const struct i2c_client *client);
-Note that starting with kernel 2.6.34, you don't have to set the `data' field
+Note that starting with kernel 2.6.34, you don't have to set the ``data`` field
to NULL in remove() or if probe() failed anymore. The i2c-core does this
automatically on these occasions. Those are also the only times the core will
touch this field.
@@ -92,25 +100,25 @@ but many chips have some kind of register-value idea that can easily
be encapsulated.
The below functions are simple examples, and should not be copied
-literally.
+literally::
-int foo_read_value(struct i2c_client *client, u8 reg)
-{
+ int foo_read_value(struct i2c_client *client, u8 reg)
+ {
if (reg < 0x10) /* byte-sized register */
return i2c_smbus_read_byte_data(client, reg);
else /* word-sized register */
return i2c_smbus_read_word_data(client, reg);
-}
+ }
-int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
-{
+ int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
+ {
if (reg == 0x10) /* Impossible to write - driver error! */
return -EINVAL;
else if (reg < 0x10) /* byte-sized register */
return i2c_smbus_write_byte_data(client, reg, value);
else /* word-sized register */
return i2c_smbus_write_word_data(client, reg, value);
-}
+ }
Probing and attaching
@@ -145,6 +153,8 @@ I2C device drivers using this binding model work just like any other
kind of driver in Linux: they provide a probe() method to bind to
those devices, and a remove() method to unbind.
+::
+
static int foo_probe(struct i2c_client *client,
const struct i2c_device_id *id);
static int foo_remove(struct i2c_client *client);
@@ -240,37 +250,41 @@ When the kernel is booted, or when your foo driver module is inserted,
you have to do some initializing. Fortunately, just registering the
driver module is usually enough.
-static int __init foo_init(void)
-{
+::
+
+ static int __init foo_init(void)
+ {
return i2c_add_driver(&foo_driver);
-}
-module_init(foo_init);
+ }
+ module_init(foo_init);
-static void __exit foo_cleanup(void)
-{
+ static void __exit foo_cleanup(void)
+ {
i2c_del_driver(&foo_driver);
-}
-module_exit(foo_cleanup);
+ }
+ module_exit(foo_cleanup);
-The module_i2c_driver() macro can be used to reduce above code.
+ The module_i2c_driver() macro can be used to reduce above code.
-module_i2c_driver(foo_driver);
+ module_i2c_driver(foo_driver);
-Note that some functions are marked by `__init'. These functions can
+Note that some functions are marked by ``__init``. These functions can
be removed after kernel booting (or module loading) is completed.
-Likewise, functions marked by `__exit' are dropped by the compiler when
+Likewise, functions marked by ``__exit`` are dropped by the compiler when
the code is built into the kernel, as they would never be called.
Driver Information
==================
-/* Substitute your own name and email address */
-MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
-MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+::
-/* a few non-GPL license types are also allowed */
-MODULE_LICENSE("GPL");
+ /* Substitute your own name and email address */
+ MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
+ MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+
+ /* a few non-GPL license types are also allowed */
+ MODULE_LICENSE("GPL");
Power Management
@@ -323,6 +337,8 @@ commands, but only some of them understand plain I2C!
Plain I2C communication
-----------------------
+::
+
int i2c_master_send(struct i2c_client *client, const char *buf,
int count);
int i2c_master_recv(struct i2c_client *client, char *buf, int count);
@@ -334,6 +350,8 @@ to read/write (must be less than the length of the buffer, also should be
less than 64k since msg.len is u16.) Returned is the actual number of bytes
read/written.
+::
+
int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
int num);
@@ -343,13 +361,15 @@ stop bit is sent between transaction. The i2c_msg structure contains
for each message the client address, the number of bytes of the message
and the message data itself.
-You can read the file `i2c-protocol' for more information about the
+You can read the file ``i2c-protocol`` for more information about the
actual I2C protocol.
SMBus communication
-------------------
+::
+
s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
unsigned short flags, char read_write, u8 command,
int size, union i2c_smbus_data *data);
@@ -357,6 +377,8 @@ SMBus communication
This is the generic SMBus function. All functions below are implemented
in terms of it. Never use this function directly!
+::
+
s32 i2c_smbus_read_byte(struct i2c_client *client);
s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);
s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);
@@ -376,7 +398,7 @@ in terms of it. Never use this function directly!
const u8 *values);
These ones were removed from i2c-core because they had no users, but could
-be added back later if needed:
+be added back later if needed::
s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);
s32 i2c_smbus_process_call(struct i2c_client *client,
@@ -389,7 +411,7 @@ transactions return 0 on success; the 'read' transactions return the read
value, except for block transactions, which return the number of values
read. The block buffers need not be longer than 32 bytes.
-You can read the file `smbus-protocol' for more information about the
+You can read the file ``smbus-protocol`` for more information about the
actual SMBus protocol.
@@ -397,7 +419,7 @@ General purpose routines
========================
Below all general purpose routines are listed, that were not mentioned
-before.
+before::
/* Return the adapter number for a specific adapter */
int i2c_adapter_id(struct i2c_adapter *adap);
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 13c3188f6a68..ded1081e8d5f 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -104,6 +104,7 @@ needed).
fb/index
fpga/index
hid/index
+ i2c/index
iio/index
infiniband/index
leds/index
diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602
index a45702865a38..0feffd5af411 100644
--- a/Documentation/spi/spi-sc18is602
+++ b/Documentation/spi/spi-sc18is602
@@ -17,7 +17,7 @@ kernel's SPI core subsystem.
The driver does not probe for supported chips, since the SI18IS602/603 does not
support Chip ID registers. You will have to instantiate the devices explicitly.
-Please see Documentation/i2c/instantiating-devices for details.
+Please see Documentation/i2c/instantiating-devices.rst for details.
Usage Notes
diff --git a/MAINTAINERS b/MAINTAINERS
index 5d4da1035a03..ce925b6e3bcc 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -666,7 +666,7 @@ ALI1563 I2C DRIVER
M: Rudolf Marek <r.marek@assembler.cz>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-ali1563
+F: Documentation/i2c/busses/i2c-ali1563.rst
F: drivers/i2c/busses/i2c-ali1563.c
ALLEGRO DVT VIDEO IP CORE DRIVER
@@ -6657,7 +6657,7 @@ L: linux-i2c@vger.kernel.org
S: Supported
F: drivers/i2c/muxes/i2c-mux-gpio.c
F: include/linux/platform_data/i2c-mux-gpio.h
-F: Documentation/i2c/muxes/i2c-mux-gpio
+F: Documentation/i2c/muxes/i2c-mux-gpio.rst
GENERIC HDLC (WAN) DRIVERS
M: Krzysztof Halasa <khc@pm.waw.pl>
@@ -7393,14 +7393,14 @@ I2C CONTROLLER DRIVER FOR NVIDIA GPU
M: Ajay Gupta <ajayg@nvidia.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-nvidia-gpu
+F: Documentation/i2c/busses/i2c-nvidia-gpu.rst
F: drivers/i2c/busses/i2c-nvidia-gpu.c
I2C MUXES
M: Peter Rosin <peda@axentia.se>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/i2c-topology
+F: Documentation/i2c/i2c-topology.rst
F: Documentation/i2c/muxes/
F: Documentation/devicetree/bindings/i2c/i2c-mux*
F: Documentation/devicetree/bindings/i2c/i2c-arb*
@@ -7420,8 +7420,8 @@ I2C OVER PARALLEL PORT
M: Jean Delvare <jdelvare@suse.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-parport
-F: Documentation/i2c/busses/i2c-parport-light
+F: Documentation/i2c/busses/i2c-parport.rst
+F: Documentation/i2c/busses/i2c-parport-light.rst
F: drivers/i2c/busses/i2c-parport.c
F: drivers/i2c/busses/i2c-parport-light.c
@@ -7455,7 +7455,7 @@ I2C-TAOS-EVM DRIVER
M: Jean Delvare <jdelvare@suse.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-taos-evm
+F: Documentation/i2c/busses/i2c-taos-evm.rst
F: drivers/i2c/busses/i2c-taos-evm.c
I2C-TINY-USB DRIVER
@@ -7469,19 +7469,19 @@ I2C/SMBUS CONTROLLER DRIVERS FOR PC
M: Jean Delvare <jdelvare@suse.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-ali1535
-F: Documentation/i2c/busses/i2c-ali1563
-F: Documentation/i2c/busses/i2c-ali15x3
-F: Documentation/i2c/busses/i2c-amd756
-F: Documentation/i2c/busses/i2c-amd8111
-F: Documentation/i2c/busses/i2c-i801
-F: Documentation/i2c/busses/i2c-nforce2
-F: Documentation/i2c/busses/i2c-piix4
-F: Documentation/i2c/busses/i2c-sis5595
-F: Documentation/i2c/busses/i2c-sis630
-F: Documentation/i2c/busses/i2c-sis96x
-F: Documentation/i2c/busses/i2c-via
-F: Documentation/i2c/busses/i2c-viapro
+F: Documentation/i2c/busses/i2c-ali1535.rst
+F: Documentation/i2c/busses/i2c-ali1563.rst
+F: Documentation/i2c/busses/i2c-ali15x3.rst
+F: Documentation/i2c/busses/i2c-amd756.rst
+F: Documentation/i2c/busses/i2c-amd8111.rst
+F: Documentation/i2c/busses/i2c-i801.rst
+F: Documentation/i2c/busses/i2c-nforce2.rst
+F: Documentation/i2c/busses/i2c-piix4.rst
+F: Documentation/i2c/busses/i2c-sis5595.rst
+F: Documentation/i2c/busses/i2c-sis630.rst
+F: Documentation/i2c/busses/i2c-sis96x.rst
+F: Documentation/i2c/busses/i2c-via.rst
+F: Documentation/i2c/busses/i2c-viapro.rst
F: drivers/i2c/busses/i2c-ali1535.c
F: drivers/i2c/busses/i2c-ali1563.c
F: drivers/i2c/busses/i2c-ali15x3.c
@@ -7510,7 +7510,7 @@ M: Seth Heasley <seth.heasley@intel.com>
M: Neil Horman <nhorman@tuxdriver.com>
L: linux-i2c@vger.kernel.org
F: drivers/i2c/busses/i2c-ismt.c
-F: Documentation/i2c/busses/i2c-ismt
+F: Documentation/i2c/busses/i2c-ismt.rst
I2C/SMBUS STUB DRIVER
M: Jean Delvare <jdelvare@suse.com>
@@ -10236,7 +10236,7 @@ L: linux-i2c@vger.kernel.org
S: Supported
F: drivers/i2c/busses/i2c-mlxcpld.c
F: drivers/i2c/muxes/i2c-mux-mlxcpld.c
-F: Documentation/i2c/busses/i2c-mlxcpld
+F: Documentation/i2c/busses/i2c-mlxcpld.rst
MELLANOX MLXCPLD LED DRIVER
M: Vadim Pasternak <vadimp@mellanox.com>
@@ -11857,7 +11857,7 @@ M: Andrew Lunn <andrew@lunn.ch>
L: linux-i2c@vger.kernel.org
S: Maintained
F: Documentation/devicetree/bindings/i2c/i2c-ocores.txt
-F: Documentation/i2c/busses/i2c-ocores
+F: Documentation/i2c/busses/i2c-ocores.rst
F: drivers/i2c/busses/i2c-ocores.c
F: include/linux/platform_data/i2c-ocores.h
@@ -14141,7 +14141,7 @@ F: net/sctp/
SCx200 CPU SUPPORT
M: Jim Cromie <jim.cromie@gmail.com>
S: Odd Fixes
-F: Documentation/i2c/busses/scx200_acb
+F: Documentation/i2c/busses/scx200_acb.rst
F: arch/x86/platform/scx200/
F: drivers/watchdog/scx200_wdt.c
F: drivers/i2c/busses/scx200*
diff --git a/Next/merge.log b/Next/merge.log
index e9f5123f59ca..b45b3201b1d6 100644
--- a/Next/merge.log
+++ b/Next/merge.log
@@ -2954,7 +2954,7 @@ $ git diff -M --stat --summary HEAD^..
Documentation/devicetree/bindings/i2c/i2c-omap.txt | 1 +
.../devicetree/bindings/i2c/i2c-sun6i-p2wi.txt | 41 ---
.../bindings/i2c/marvell,mv64xxx-i2c.yaml | 124 +++++++
- Documentation/i2c/busses/i2c-i801 | 3 +-
+ Documentation/i2c/busses/i2c-i801.rst | 3 +-
MAINTAINERS | 7 +
arch/arm/include/asm/hardware/iop3xx.h | 2 +
arch/arm/mach-iop32x/em7210.c | 3 +
@@ -3251,8 +3251,8 @@ $ git diff -M --stat --summary HEAD^..
Documentation/fpga/index.rst | 17 +
Documentation/gpu/msm-crash-dump.rst | 2 +
Documentation/hid/hid-transport.txt | 6 +-
- Documentation/i2c/instantiating-devices | 4 +-
- Documentation/i2c/upgrading-clients | 4 +-
+ Documentation/i2c/instantiating-devices.rst | 4 +-
+ Documentation/i2c/upgrading-clients.rst | 4 +-
Documentation/ide/changelogs.rst | 17 +
Documentation/ide/{ide-tape.txt => ide-tape.rst} | 23 +-
Documentation/ide/{ide.txt => ide.rst} | 147 +-
diff --git a/drivers/hwmon/atxp1.c b/drivers/hwmon/atxp1.c
index e232fa948833..79b8df258371 100644
--- a/drivers/hwmon/atxp1.c
+++ b/drivers/hwmon/atxp1.c
@@ -5,7 +5,7 @@
*
* The ATXP1 can reside on I2C addresses 0x37 or 0x4e. The chip is
* not auto-detected by the driver and must be instantiated explicitly.
- * See Documentation/i2c/instantiating-devices for more information.
+ * See Documentation/i2c/instantiating-devices.rst for more information.
*/
#include <linux/kernel.h>
diff --git a/drivers/hwmon/smm665.c b/drivers/hwmon/smm665.c
index d8c91c2cb8cf..9ae0dc28b9cf 100644
--- a/drivers/hwmon/smm665.c
+++ b/drivers/hwmon/smm665.c
@@ -197,7 +197,7 @@ static int smm665_read_adc(struct smm665_data *data, int adc)
if (rv != -ENXIO) {
/*
* We expect ENXIO to reflect NACK
- * (per Documentation/i2c/fault-codes).
+ * (per Documentation/i2c/fault-codes.rst).
* Everything else is an error.
*/
dev_dbg(&client->dev,
diff --git a/drivers/i2c/Kconfig b/drivers/i2c/Kconfig
index abedd55a1264..1474e57ecafc 100644
--- a/drivers/i2c/Kconfig
+++ b/drivers/i2c/Kconfig
@@ -54,7 +54,7 @@ config I2C_CHARDEV
Say Y here to use i2c-* device files, usually found in the /dev
directory on your system. They make it possible to have user-space
programs use the I2C bus. Information on how to do this is
- contained in the file <file:Documentation/i2c/dev-interface>.
+ contained in the file <file:Documentation/i2c/dev-interface.rst>.
This support is also available as a module. If so, the module
will be called i2c-dev.
@@ -107,7 +107,7 @@ config I2C_STUB
especially for certain kinds of sensor chips.
If you do build this module, be sure to read the notes and warnings
- in <file:Documentation/i2c/i2c-stub>.
+ in <file:Documentation/i2c/i2c-stub.rst>.
If you don't know what to do here, definitely say N.
diff --git a/drivers/i2c/busses/Kconfig b/drivers/i2c/busses/Kconfig
index 68b677be1fa4..e4be46644e8b 100644
--- a/drivers/i2c/busses/Kconfig
+++ b/drivers/i2c/busses/Kconfig
@@ -1205,7 +1205,7 @@ config I2C_PARPORT
and makes it easier to add support for new devices.
An adapter type parameter is now mandatory. Please read the file
- Documentation/i2c/busses/i2c-parport for details.
+ Documentation/i2c/busses/i2c-parport.rst for details.
Another driver exists, named i2c-parport-light, which doesn't depend
on the parport driver. This is meant for embedded systems. Don't say
diff --git a/drivers/i2c/busses/i2c-i801.c b/drivers/i2c/busses/i2c-i801.c
index 1e7f6ae62b4c..a215b336bf5c 100644
--- a/drivers/i2c/busses/i2c-i801.c
+++ b/drivers/i2c/busses/i2c-i801.c
@@ -76,7 +76,7 @@
* SMBus Host Notify yes
* Interrupt processing yes
*
- * See the file Documentation/i2c/busses/i2c-i801 for details.
+ * See the file Documentation/i2c/busses/i2c-i801.rst for details.
*/
#include <linux/interrupt.h>
diff --git a/drivers/i2c/busses/i2c-taos-evm.c b/drivers/i2c/busses/i2c-taos-evm.c
index c82e78f57386..37347c93e8e0 100644
--- a/drivers/i2c/busses/i2c-taos-evm.c
+++ b/drivers/i2c/busses/i2c-taos-evm.c
@@ -125,7 +125,7 @@ static int taos_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
/*
* Voluntarily dropping error code of kstrtou8 since all
* error code that it could return are invalid according
- * to Documentation/i2c/fault-codes.
+ * to Documentation/i2c/fault-codes.rst.
*/
if (kstrtou8(p + 1, 16, &data->byte))
return -EPROTO;
diff --git a/drivers/i2c/i2c-core-base.c b/drivers/i2c/i2c-core-base.c
index e77bab2fb467..56b42558575e 100644
--- a/drivers/i2c/i2c-core-base.c
+++ b/drivers/i2c/i2c-core-base.c
@@ -2205,7 +2205,7 @@ static int i2c_detect_address(struct i2c_client *temp_client,
dev_warn(&adapter->dev,
"This adapter will soon drop class based instantiation of devices. "
"Please make sure client 0x%02x gets instantiated by other means. "
- "Check 'Documentation/i2c/instantiating-devices' for details.\n",
+ "Check 'Documentation/i2c/instantiating-devices.rst' for details.\n",
info.addr);
dev_dbg(&adapter->dev, "Creating %s at 0x%02x\n",
@@ -2235,7 +2235,7 @@ static int i2c_detect(struct i2c_adapter *adapter, struct i2c_driver *driver)
if (adapter->class == I2C_CLASS_DEPRECATED) {
dev_dbg(&adapter->dev,
"This adapter dropped support for I2C classes and won't auto-detect %s devices anymore. "
- "If you need it, check 'Documentation/i2c/instantiating-devices' for alternatives.\n",
+ "If you need it, check 'Documentation/i2c/instantiating-devices.rst' for alternatives.\n",
driver->driver.name);
return 0;
}
diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
index 8f99c005458a..d28974ad9e0e 100644
--- a/drivers/iio/dummy/iio_simple_dummy.c
+++ b/drivers/iio/dummy/iio_simple_dummy.c
@@ -693,7 +693,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
* Varies depending on bus type of the device. As there is no device
* here, call probe directly. For information on device registration
* i2c:
- * Documentation/i2c/writing-clients
+ * Documentation/i2c/writing-clients.rst
* spi:
* Documentation/spi/spi-summary
*/
diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
index 225a8df1d4e9..1803f3cab39f 100644
--- a/drivers/rtc/rtc-ds1374.c
+++ b/drivers/rtc/rtc-ds1374.c
@@ -14,7 +14,7 @@
*/
/*
* It would be more efficient to use i2c msgs/i2c_transfer directly but, as
- * recommened in .../Documentation/i2c/writing-clients section
+ * recommened in .../Documentation/i2c/writing-clients.rst section
* "Sending and receiving", using SMBus level communication is preferred.
*/
diff --git a/include/linux/i2c.h b/include/linux/i2c.h
index fa5552c2307b..c0a78c069117 100644
--- a/include/linux/i2c.h
+++ b/include/linux/i2c.h
@@ -521,7 +521,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
*
* The return codes from the @master_xfer{_atomic} fields should indicate the
* type of error code that occurred during the transfer, as documented in the
- * Kernel Documentation file Documentation/i2c/fault-codes.
+ * Kernel Documentation file Documentation/i2c/fault-codes.rst.
*/
struct i2c_algorithm {
/*
--
2.21.0
^ permalink raw reply related [flat|nested] 14+ messages in thread
* [PATCH 4/5] docs: w1: convert to ReST and add to the kAPI group of docs
2019-06-28 21:23 [PATCH 0/5] Convert misc-devices, i2c, w1, spi and some markdown files to ReST Mauro Carvalho Chehab
` (2 preceding siblings ...)
2019-06-28 21:23 ` [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset Mauro Carvalho Chehab
@ 2019-06-28 21:23 ` Mauro Carvalho Chehab
2019-06-28 21:23 ` [PATCH 5/5] docs: spi: convert to ReST and add it to the kABI bookset Mauro Carvalho Chehab
4 siblings, 0 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 21:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Evgeniy Polyakov
The 1wire documentation was written with w1 developers in
mind, so, it makes sense to add it together with the driver-api
set.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/stable/sysfs-bus-w1 | 2 +-
.../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +-
.../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +-
Documentation/index.rst | 1 +
Documentation/w1/index.rst | 22 +++++
.../w1/masters/{ds2482 => ds2482.rst} | 17 +++-
.../w1/masters/{ds2490 => ds2490.rst} | 6 +-
Documentation/w1/masters/index.rst | 14 +++
Documentation/w1/masters/mxc-w1 | 12 ---
Documentation/w1/masters/mxc-w1.rst | 17 ++++
.../w1/masters/{omap-hdq => omap-hdq.rst} | 12 +--
.../w1/masters/{w1-gpio => w1-gpio.rst} | 21 +++--
Documentation/w1/slaves/index.rst | 16 ++++
.../w1/slaves/{w1_ds2406 => w1_ds2406.rst} | 2 +
.../w1/slaves/{w1_ds2413 => w1_ds2413.rst} | 9 ++
Documentation/w1/slaves/w1_ds2423 | 47 ----------
Documentation/w1/slaves/w1_ds2423.rst | 54 ++++++++++++
.../w1/slaves/{w1_ds2438 => w1_ds2438.rst} | 10 ++-
.../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} | 5 ++
.../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} | 15 ++--
.../w1/slaves/{w1_therm => w1_therm.rst} | 11 ++-
.../w1/{w1.generic => w1-generic.rst} | 88 +++++++++++--------
.../w1/{w1.netlink => w1-netlink.rst} | 83 +++++++++--------
23 files changed, 306 insertions(+), 164 deletions(-)
create mode 100644 Documentation/w1/index.rst
rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
create mode 100644 Documentation/w1/masters/index.rst
delete mode 100644 Documentation/w1/masters/mxc-w1
create mode 100644 Documentation/w1/masters/mxc-w1.rst
rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
create mode 100644 Documentation/w1/slaves/index.rst
rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (97%)
rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
delete mode 100644 Documentation/w1/slaves/w1_ds2423
create mode 100644 Documentation/w1/slaves/w1_ds2423.rst
rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
rename Documentation/w1/{w1.netlink => w1-netlink.rst} (79%)
diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1
index 140d85b4ae92..992dfb183ed0 100644
--- a/Documentation/ABI/stable/sysfs-bus-w1
+++ b/Documentation/ABI/stable/sysfs-bus-w1
@@ -6,6 +6,6 @@ Description: Bus scanning interval, microseconds component.
control systems are attached/generate presence for as short as
100 ms - hence the tens-to-hundreds milliseconds scan intervals
are required.
- see Documentation/w1/w1.generic for detailed information.
+ see Documentation/w1/w1-generic.rst for detailed information.
Users: any user space application which wants to know bus scanning
interval
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
index 26579ee868c9..3e1c1fa8d54d 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
@@ -2,7 +2,7 @@ What: /sys/bus/w1/devices/.../pio
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the two PIO's of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
@@ -11,5 +11,5 @@ What: /sys/bus/w1/devices/.../eeprom
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the EEPROM memory of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
index e928def14f28..534e63731a49 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
@@ -2,5 +2,5 @@ What: /sys/bus/w1/devices/.../w1_seq
Date: Apr 2015
Contact: Matt Campbell <mattrcampbell@gmail.com>
Description: Support for the DS28EA00 chain sequence function
- see Documentation/w1/slaves/w1_therm for detailed information
+ see Documentation/w1/slaves/w1_therm.rst for detailed information
Users: any user space application which wants to communicate with DS28EA00
diff --git a/Documentation/index.rst b/Documentation/index.rst
index ded1081e8d5f..38ece18f5d1e 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -115,6 +115,7 @@ needed).
power/index
target/index
timers/index
+ w1/index
watchdog/index
input/index
hwmon/index
diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst
new file mode 100644
index 000000000000..4ca0698357c4
--- /dev/null
+++ b/Documentation/w1/index.rst
@@ -0,0 +1,22 @@
+. SPDX-License-Identifier: GPL-2.0
+
+================
+1-Wire Subsystem
+================
+
+.. toctree::
+ :maxdepth: 1
+
+
+ w1-generic.rst
+ w1-netlink.rst
+ masters/index
+ slaves/index
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
+
diff --git a/Documentation/w1/masters/ds2482 b/Documentation/w1/masters/ds2482.rst
similarity index 71%
rename from Documentation/w1/masters/ds2482
rename to Documentation/w1/masters/ds2482.rst
index 56f8edace6ac..7f1558d39310 100644
--- a/Documentation/w1/masters/ds2482
+++ b/Documentation/w1/masters/ds2482.rst
@@ -1,13 +1,19 @@
+====================
Kernel driver ds2482
====================
Supported chips:
+
* Maxim DS2482-100, Maxim DS2482-800
+
Prefix: 'ds2482'
+
Addresses scanned: None
+
Datasheets:
- http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
- http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
+
+ - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
+ - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
Author: Ben Gardner <bgardner@wabtec.com>
@@ -23,9 +29,12 @@ General Remarks
---------------
Valid addresses are 0x18, 0x19, 0x1a, and 0x1b.
+
However, the device cannot be detected without writing to the i2c bus, so no
detection is done. You should instantiate the device explicitly.
-$ modprobe ds2482
-$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
+::
+
+ $ modprobe ds2482
+ $ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
diff --git a/Documentation/w1/masters/ds2490 b/Documentation/w1/masters/ds2490.rst
similarity index 98%
rename from Documentation/w1/masters/ds2490
rename to Documentation/w1/masters/ds2490.rst
index 3e091151dd80..7e5b50f9c0f5 100644
--- a/Documentation/w1/masters/ds2490
+++ b/Documentation/w1/masters/ds2490.rst
@@ -1,7 +1,9 @@
+====================
Kernel driver ds2490
====================
Supported chips:
+
* Maxim DS2490 based
Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
@@ -18,6 +20,7 @@ which has 0x81 family ID integrated chip and DS2490
low-level operational chip.
Notes and limitations.
+
- The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
- The 5V strong pullup is supported with a minimum of 5.9mA and a
maximum of 30.4 mA. (From DS2490.pdf)
@@ -65,4 +68,5 @@ Notes and limitations.
reattaching would clear the problem. usbmon output in the guest and
host did not explain the problem. My guess is a bug in either qemu
or the host OS and more likely the host OS.
--- 03-06-2008 David Fries <David@Fries.net>
+
+03-06-2008 David Fries <David@Fries.net>
diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst
new file mode 100644
index 000000000000..4442a98850ad
--- /dev/null
+++ b/Documentation/w1/masters/index.rst
@@ -0,0 +1,14 @@
+. SPDX-License-Identifier: GPL-2.0
+
+=====================
+1-wire Master Drivers
+=====================
+
+.. toctree::
+ :maxdepth: 1
+
+ ds2482
+ ds2490
+ mxc-w1
+ omap-hdq
+ w1-gpio
diff --git a/Documentation/w1/masters/mxc-w1 b/Documentation/w1/masters/mxc-w1
deleted file mode 100644
index 38be1ad65532..000000000000
--- a/Documentation/w1/masters/mxc-w1
+++ /dev/null
@@ -1,12 +0,0 @@
-Kernel driver mxc_w1
-====================
-
-Supported chips:
- * Freescale MX27, MX31 and probably other i.MX SoCs
- Datasheets:
- http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
- http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=
- Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
-
-Author: Originally based on Freescale code, prepared for mainline by
- Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/mxc-w1.rst b/Documentation/w1/masters/mxc-w1.rst
new file mode 100644
index 000000000000..334f9893103f
--- /dev/null
+++ b/Documentation/w1/masters/mxc-w1.rst
@@ -0,0 +1,17 @@
+====================
+Kernel driver mxc_w1
+====================
+
+Supported chips:
+
+ * Freescale MX27, MX31 and probably other i.MX SoCs
+
+ Datasheets:
+
+ - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
+ - http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
+
+Author:
+
+ Originally based on Freescale code, prepared for mainline by
+ Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq.rst
similarity index 90%
rename from Documentation/w1/masters/omap-hdq
rename to Documentation/w1/masters/omap-hdq.rst
index 234522709a5f..345298a59e50 100644
--- a/Documentation/w1/masters/omap-hdq
+++ b/Documentation/w1/masters/omap-hdq.rst
@@ -1,9 +1,10 @@
-Kernel driver for omap HDQ/1-wire module.
+========================================
+Kernel driver for omap HDQ/1-wire module
========================================
Supported chips:
================
- HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
+HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
A useful link about HDQ basics:
===============================
@@ -40,9 +41,10 @@ driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1.
Please note to load both the modules with a different ID if required, but note
that the ID used should be same for both master and slave driver loading.
-e.g:
-insmod omap_hdq.ko W1_ID=2
-inamod w1_bq27000.ko F_ID=2
+e.g::
+
+ insmod omap_hdq.ko W1_ID=2
+ inamod w1_bq27000.ko F_ID=2
The driver also supports 1-wire mode. In this mode, there is no need to
pass slave ID as parameter. The driver will auto-detect slaves connected
diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio.rst
similarity index 75%
rename from Documentation/w1/masters/w1-gpio
rename to Documentation/w1/masters/w1-gpio.rst
index 623961d9e83f..18fdb7366372 100644
--- a/Documentation/w1/masters/w1-gpio
+++ b/Documentation/w1/masters/w1-gpio.rst
@@ -1,3 +1,4 @@
+=====================
Kernel driver w1-gpio
=====================
@@ -16,28 +17,30 @@ Documentation/devicetree/bindings/w1/w1-gpio.txt
Example (mach-at91)
-------------------
-#include <linux/gpio/machine.h>
-#include <linux/w1-gpio.h>
+::
-static struct gpiod_lookup_table foo_w1_gpiod_table = {
+ #include <linux/gpio/machine.h>
+ #include <linux/w1-gpio.h>
+
+ static struct gpiod_lookup_table foo_w1_gpiod_table = {
.dev_id = "w1-gpio",
.table = {
GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0,
GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN),
},
-};
+ };
-static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
+ static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
.ext_pullup_enable_pin = -EINVAL,
-};
+ };
-static struct platform_device foo_w1_device = {
+ static struct platform_device foo_w1_device = {
.name = "w1-gpio",
.id = -1,
.dev.platform_data = &foo_w1_gpio_pdata,
-};
+ };
-...
+ ...
at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1);
at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1);
gpiod_add_lookup_table(&foo_w1_gpiod_table);
diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst
new file mode 100644
index 000000000000..d0697b202f09
--- /dev/null
+++ b/Documentation/w1/slaves/index.rst
@@ -0,0 +1,16 @@
+. SPDX-License-Identifier: GPL-2.0
+
+====================
+1-wire Slave Drivers
+====================
+
+.. toctree::
+ :maxdepth: 1
+
+ w1_ds2406
+ w1_ds2413
+ w1_ds2423
+ w1_ds2438
+ w1_ds28e04
+ w1_ds28e17
+ w1_therm
diff --git a/Documentation/w1/slaves/w1_ds2406 b/Documentation/w1/slaves/w1_ds2406.rst
similarity index 97%
rename from Documentation/w1/slaves/w1_ds2406
rename to Documentation/w1/slaves/w1_ds2406.rst
index 8137fe6f6c3d..ec82f2614721 100644
--- a/Documentation/w1/slaves/w1_ds2406
+++ b/Documentation/w1/slaves/w1_ds2406.rst
@@ -1,7 +1,9 @@
+=======================
w1_ds2406 kernel driver
=======================
Supported chips:
+
* Maxim DS2406 (and other family 0x12) addressable switches
Author: Scott Alfter <scott@alfter.us>
diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413.rst
similarity index 81%
rename from Documentation/w1/slaves/w1_ds2413
rename to Documentation/w1/slaves/w1_ds2413.rst
index 936263a8ccb4..c15bb5b919b7 100644
--- a/Documentation/w1/slaves/w1_ds2413
+++ b/Documentation/w1/slaves/w1_ds2413.rst
@@ -1,11 +1,16 @@
+=======================
Kernel driver w1_ds2413
=======================
Supported chips:
+
* Maxim DS2413 1-Wire Dual Channel Addressable Switch
supported family codes:
+
+ ================ ====
W1_FAMILY_DS2413 0x3A
+ ================ ====
Author: Mariusz Bialonczyk <manio@skyboo.net>
@@ -20,11 +25,13 @@ Reading state
The "state" file provides one-byte value which is in the same format as for
the chip PIO_ACCESS_READ command (refer the datasheet for details):
+======== =============================================================
Bit 0: PIOA Pin State
Bit 1: PIOA Output Latch State
Bit 2: PIOB Pin State
Bit 3: PIOB Output Latch State
Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
+======== =============================================================
This file is readonly.
@@ -34,9 +41,11 @@ You can set the PIO pins using the "output" file.
It is writable, you can write one-byte value to this sysfs file.
Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
+======== ======================================
Bit 0: PIOA
Bit 1: PIOB
Bit 2-7: No matter (driver will set it to "1"s)
+======== ======================================
The chip has some kind of basic protection against transmission errors.
diff --git a/Documentation/w1/slaves/w1_ds2423 b/Documentation/w1/slaves/w1_ds2423
deleted file mode 100644
index 3f98b505a0ee..000000000000
--- a/Documentation/w1/slaves/w1_ds2423
+++ /dev/null
@@ -1,47 +0,0 @@
-Kernel driver w1_ds2423
-=======================
-
-Supported chips:
- * Maxim DS2423 based counter devices.
-
-supported family codes:
- W1_THERM_DS2423 0x1D
-
-Author: Mika Laitio <lamikr@pilppa.org>
-
-Description
------------
-
-Support is provided through the sysfs w1_slave file. Each opening and
-read sequence of w1_slave file initiates the read of counters and ram
-available in DS2423 pages 12 - 15.
-
-Result of each page is provided as an ASCII output where each counter
-value and associated ram buffer is outpputed to own line.
-
-Each lines will contain the values of 42 bytes read from the counter and
-memory page along the crc=YES or NO for indicating whether the read operation
-was successful and CRC matched.
-If the operation was successful, there is also in the end of each line
-a counter value expressed as an integer after c=
-
-Meaning of 42 bytes represented is following:
- - 1 byte from ram page
- - 4 bytes for the counter value
- - 4 zero bytes
- - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
- - 31 remaining bytes from the ram page
- - crc=YES/NO indicating whether read was ok and crc matched
- - c=<int> current counter value
-
-example from the successful read:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
-00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
-
-example from the read with crc errors:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2423.rst b/Documentation/w1/slaves/w1_ds2423.rst
new file mode 100644
index 000000000000..755d659ad997
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2423.rst
@@ -0,0 +1,54 @@
+Kernel driver w1_ds2423
+=======================
+
+Supported chips:
+
+ * Maxim DS2423 based counter devices.
+
+supported family codes:
+
+ =============== ====
+ W1_THERM_DS2423 0x1D
+ =============== ====
+
+Author: Mika Laitio <lamikr@pilppa.org>
+
+Description
+-----------
+
+Support is provided through the sysfs w1_slave file. Each opening and
+read sequence of w1_slave file initiates the read of counters and ram
+available in DS2423 pages 12 - 15.
+
+Result of each page is provided as an ASCII output where each counter
+value and associated ram buffer is outpputed to own line.
+
+Each lines will contain the values of 42 bytes read from the counter and
+memory page along the crc=YES or NO for indicating whether the read operation
+was successful and CRC matched.
+If the operation was successful, there is also in the end of each line
+a counter value expressed as an integer after c=
+
+Meaning of 42 bytes represented is following:
+
+ - 1 byte from ram page
+ - 4 bytes for the counter value
+ - 4 zero bytes
+ - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
+ - 31 remaining bytes from the ram page
+ - crc=YES/NO indicating whether read was ok and crc matched
+ - c=<int> current counter value
+
+example from the successful read::
+
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
+ 00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
+
+example from the read with crc errors::
+
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438.rst
similarity index 93%
rename from Documentation/w1/slaves/w1_ds2438
rename to Documentation/w1/slaves/w1_ds2438.rst
index e64f65a09387..a29309a3f8e5 100644
--- a/Documentation/w1/slaves/w1_ds2438
+++ b/Documentation/w1/slaves/w1_ds2438.rst
@@ -2,10 +2,13 @@ Kernel driver w1_ds2438
=======================
Supported chips:
+
* Maxim DS2438 Smart Battery Monitor
supported family codes:
+ ================ ====
W1_FAMILY_DS2438 0x26
+ ================ ====
Author: Mariusz Bialonczyk <manio@skyboo.net>
@@ -56,8 +59,11 @@ Opening and reading this file initiates the CONVERT_V (voltage conversion)
command of the chip.
Depending on a sysfs filename a different input for the A/D will be selected:
-vad: general purpose A/D input (VAD)
-vdd: battery input (VDD)
+
+vad:
+ general purpose A/D input (VAD)
+vdd:
+ battery input (VDD)
After the voltage conversion the value is returned as decimal ASCII.
Note: To get a volts the value has to be divided by 100.
diff --git a/Documentation/w1/slaves/w1_ds28e04 b/Documentation/w1/slaves/w1_ds28e04.rst
similarity index 93%
rename from Documentation/w1/slaves/w1_ds28e04
rename to Documentation/w1/slaves/w1_ds28e04.rst
index 7819b65cfa48..b12b118890d3 100644
--- a/Documentation/w1/slaves/w1_ds28e04
+++ b/Documentation/w1/slaves/w1_ds28e04.rst
@@ -1,11 +1,16 @@
+========================
Kernel driver w1_ds28e04
========================
Supported chips:
+
* Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
supported family codes:
+
+ ================= ====
W1_FAMILY_DS28E04 0x1C
+ ================= ====
Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de>
diff --git a/Documentation/w1/slaves/w1_ds28e17 b/Documentation/w1/slaves/w1_ds28e17.rst
similarity index 88%
rename from Documentation/w1/slaves/w1_ds28e17
rename to Documentation/w1/slaves/w1_ds28e17.rst
index 7fcfad5b4a37..36fd0517ea30 100644
--- a/Documentation/w1/slaves/w1_ds28e17
+++ b/Documentation/w1/slaves/w1_ds28e17.rst
@@ -1,11 +1,16 @@
+========================
Kernel driver w1_ds28e17
========================
Supported chips:
+
* Maxim DS28E17 1-Wire-to-I2C Master Bridge
supported family codes:
+
+ ================= ====
W1_FAMILY_DS28E17 0x19
+ ================= ====
Author: Jan Kandziora <jjj@gmx.de>
@@ -20,11 +25,11 @@ a DS28E17 can be accessed by the kernel or userspace tools as if they were
connected to a "native" I2C bus master.
-An udev rule like the following
--------------------------------------------------------------------------------
-SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
- SYMLINK+="i2c-$attr{name}"
--------------------------------------------------------------------------------
+An udev rule like the following::
+
+ SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
+ SYMLINK+="i2c-$attr{name}"
+
may be used to create stable /dev/i2c- entries based on the unique id of the
DS28E17 chip.
diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm.rst
similarity index 95%
rename from Documentation/w1/slaves/w1_therm
rename to Documentation/w1/slaves/w1_therm.rst
index d1f93af36f38..90531c340a07 100644
--- a/Documentation/w1/slaves/w1_therm
+++ b/Documentation/w1/slaves/w1_therm.rst
@@ -1,7 +1,9 @@
+======================
Kernel driver w1_therm
-====================
+======================
Supported chips:
+
* Maxim ds18*20 based temperature sensors.
* Maxim ds1825 based temperature sensors.
@@ -13,12 +15,16 @@ Description
w1_therm provides basic temperature conversion for ds18*20 devices, and the
ds28ea00 device.
-supported family codes:
+
+Supported family codes:
+
+==================== ====
W1_THERM_DS18S20 0x10
W1_THERM_DS1822 0x22
W1_THERM_DS18B20 0x28
W1_THERM_DS1825 0x3B
W1_THERM_DS28EA00 0x42
+==================== ====
Support is provided through the sysfs w1_slave file. Each open and
read sequence will initiate a temperature conversion then provide two
@@ -51,6 +57,7 @@ If so, it will activate the master's strong pullup.
In case the detection of parasite devices using this command fails
(seems to be the case with some DS18S20) the strong pullup can
be force-enabled.
+
If the strong pullup is enabled, the master's strong pullup will be
driven when the conversion is taking place, provided the master driver
does support the strong pullup (or it falls back to a pullup
diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1-generic.rst
similarity index 59%
rename from Documentation/w1/w1.generic
rename to Documentation/w1/w1-generic.rst
index c51b1ab012d0..da4e8b4e9b01 100644
--- a/Documentation/w1/w1.generic
+++ b/Documentation/w1/w1-generic.rst
@@ -1,5 +1,7 @@
-The 1-wire (w1) subsystem
-------------------------------------------------------------------
+=========================================
+Introduction to the 1-wire (w1) subsystem
+=========================================
+
The 1-wire bus is a simple master-slave bus that communicates via a single
signal wire (plus ground, so two wires).
@@ -12,14 +14,16 @@ communication with slaves.
All w1 slave devices must be connected to a w1 bus master device.
Example w1 master devices:
- DS9490 usb device
- W1-over-GPIO
- DS2482 (i2c to w1 bridge)
- Emulated devices, such as a RS232 converter, parallel port adapter, etc
+
+ - DS9490 usb device
+ - W1-over-GPIO
+ - DS2482 (i2c to w1 bridge)
+ - Emulated devices, such as a RS232 converter, parallel port adapter, etc
What does the w1 subsystem do?
-------------------------------------------------------------------
+------------------------------
+
When a w1 master driver registers with the w1 subsystem, the following occurs:
- sysfs entries for that w1 master are created
@@ -43,24 +47,28 @@ be read, since no device was selected.
W1 device families
-------------------------------------------------------------------
+------------------
+
Slave devices are handled by a driver written for a family of w1 devices.
A family driver populates a struct w1_family_ops (see w1_family.h) and
registers with the w1 subsystem.
Current family drivers:
-w1_therm - (ds18?20 thermal sensor family driver)
+
+w1_therm
+ - (ds18?20 thermal sensor family driver)
provides temperature reading function which is bound to ->rbin() method
of the above w1_family_ops structure.
-w1_smem - driver for simple 64bit memory cell provides ID reading method.
+w1_smem
+ - driver for simple 64bit memory cell provides ID reading method.
You can call above methods by reading appropriate sysfs files.
What does a w1 master driver need to implement?
-------------------------------------------------------------------
+-----------------------------------------------
The driver for w1 bus master must provide at minimum two functions.
@@ -75,25 +83,26 @@ See struct w1_bus_master definition in w1.h for details.
w1 master sysfs interface
-------------------------------------------------------------------
-<xx-xxxxxxxxxxxx> - A directory for a found device. The format is family-serial
-bus - (standard) symlink to the w1 bus
-driver - (standard) symlink to the w1 driver
-w1_master_add - (rw) manually register a slave device
-w1_master_attempts - (ro) the number of times a search was attempted
-w1_master_max_slave_count
- - (rw) maximum number of slaves to search for at a time
-w1_master_name - (ro) the name of the device (w1_bus_masterX)
-w1_master_pullup - (rw) 5V strong pullup 0 enabled, 1 disabled
-w1_master_remove - (rw) manually remove a slave device
-w1_master_search - (rw) the number of searches left to do,
- -1=continual (default)
-w1_master_slave_count
- - (ro) the number of slaves found
-w1_master_slaves - (ro) the names of the slaves, one per line
-w1_master_timeout - (ro) the delay in seconds between searches
-w1_master_timeout_us
- - (ro) the delay in microseconds beetwen searches
+-------------------------
+
+========================= =====================================================
+<xx-xxxxxxxxxxxx> A directory for a found device. The format is
+ family-serial
+bus (standard) symlink to the w1 bus
+driver (standard) symlink to the w1 driver
+w1_master_add (rw) manually register a slave device
+w1_master_attempts (ro) the number of times a search was attempted
+w1_master_max_slave_count (rw) maximum number of slaves to search for at a time
+w1_master_name (ro) the name of the device (w1_bus_masterX)
+w1_master_pullup (rw) 5V strong pullup 0 enabled, 1 disabled
+w1_master_remove (rw) manually remove a slave device
+w1_master_search (rw) the number of searches left to do,
+ -1=continual (default)
+w1_master_slave_count (ro) the number of slaves found
+w1_master_slaves (ro) the names of the slaves, one per line
+w1_master_timeout (ro) the delay in seconds between searches
+w1_master_timeout_us (ro) the delay in microseconds beetwen searches
+========================= =====================================================
If you have a w1 bus that never changes (you don't add or remove devices),
you can set the module parameter search_count to a small positive number
@@ -111,11 +120,14 @@ decrements w1_master_search by 1 (down to 0) and increments
w1_master_attempts by 1.
w1 slave sysfs interface
-------------------------------------------------------------------
-bus - (standard) symlink to the w1 bus
-driver - (standard) symlink to the w1 driver
-name - the device name, usually the same as the directory name
-w1_slave - (optional) a binary file whose meaning depends on the
- family driver
-rw - (optional) created for slave devices which do not have
- appropriate family driver. Allows to read/write binary data.
+------------------------
+
+=================== ============================================================
+bus (standard) symlink to the w1 bus
+driver (standard) symlink to the w1 driver
+name the device name, usually the same as the directory name
+w1_slave (optional) a binary file whose meaning depends on the
+ family driver
+rw (optional) created for slave devices which do not have
+ appropriate family driver. Allows to read/write binary data.
+=================== ============================================================
diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1-netlink.rst
similarity index 79%
rename from Documentation/w1/w1.netlink
rename to Documentation/w1/w1-netlink.rst
index 94ad4c420828..138a53c2f950 100644
--- a/Documentation/w1/w1.netlink
+++ b/Documentation/w1/w1-netlink.rst
@@ -1,22 +1,26 @@
-Userspace communication protocol over connector [1].
+===============================================
+Userspace communication protocol over connector
+===============================================
-
-Message types.
+Message types
=============
There are three types of messages between w1 core and userspace:
+
1. Events. They are generated each time a new master or slave device
- is found either due to automatic or requested search.
+ is found either due to automatic or requested search.
2. Userspace commands.
3. Replies to userspace commands.
-Protocol.
+Protocol
========
-[struct cn_msg] - connector header.
+::
+
+ [struct cn_msg] - connector header.
Its length field is equal to size of the attached data
-[struct w1_netlink_msg] - w1 netlink header.
+ [struct w1_netlink_msg] - w1 netlink header.
__u8 type - message type.
W1_LIST_MASTERS
list current bus masters
@@ -40,7 +44,7 @@ Protocol.
} mst;
} id;
-[struct w1_netlink_cmd] - command for given master or slave device.
+ [struct w1_netlink_cmd] - command for given master or slave device.
__u8 cmd - command opcode.
W1_CMD_READ - read command
W1_CMD_WRITE - write command
@@ -71,18 +75,18 @@ when it is added to w1 core.
Currently replies to userspace commands are only generated for read
command request. One reply is generated exactly for one w1_netlink_cmd
read request. Replies are not combined when sent - i.e. typical reply
-messages looks like the following:
+messages looks like the following::
-[cn_msg][w1_netlink_msg][w1_netlink_cmd]
-cn_msg.len = sizeof(struct w1_netlink_msg) +
+ [cn_msg][w1_netlink_msg][w1_netlink_cmd]
+ cn_msg.len = sizeof(struct w1_netlink_msg) +
sizeof(struct w1_netlink_cmd) +
cmd->len;
-w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
-w1_netlink_cmd.len = cmd->len;
+ w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
+ w1_netlink_cmd.len = cmd->len;
Replies to W1_LIST_MASTERS should send a message back to the userspace
which will contain list of all registered master ids in the following
-format:
+format::
cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
w1_netlink_msg) plus number of masters multiplied by 4)
@@ -90,39 +94,47 @@ format:
number of masters multiplied by 4 (u32 size))
id0 ... idN
- Each message is at most 4k in size, so if number of master devices
- exceeds this, it will be split into several messages.
+Each message is at most 4k in size, so if number of master devices
+exceeds this, it will be split into several messages.
W1 search and alarm search commands.
-request:
-[cn_msg]
- [w1_netlink_msg type = W1_MASTER_CMD
+
+request::
+
+ [cn_msg]
+ [w1_netlink_msg type = W1_MASTER_CMD
id is equal to the bus master id to use for searching]
- [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
+ [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
+
+reply::
-reply:
[cn_msg, ack = 1 and increasing, 0 means the last message,
seq is equal to the request seq]
[w1_netlink_msg type = W1_MASTER_CMD]
[w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
len is equal to number of IDs multiplied by 8]
[64bit-id0 ... 64bit-idN]
+
Length in each header corresponds to the size of the data behind it, so
w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
- Can be zero.
-w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
-cn_msg->len = sizeof(struct w1_netlink_msg) +
+Can be zero.
+
+::
+
+ w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
+ cn_msg->len = sizeof(struct w1_netlink_msg) +
sizeof(struct w1_netlink_cmd) +
N*8;
-W1 reset command.
-[cn_msg]
- [w1_netlink_msg type = W1_MASTER_CMD
+W1 reset command::
+
+ [cn_msg]
+ [w1_netlink_msg type = W1_MASTER_CMD
id is equal to the bus master id to use for searching]
- [w1_netlink_cmd cmd = W1_CMD_RESET]
+ [w1_netlink_cmd cmd = W1_CMD_RESET]
-Command status replies.
+Command status replies
======================
Each command (either root, master or slave with or without w1_netlink_cmd
@@ -150,7 +162,7 @@ All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
even if there were errors, only length mismatch interrupts message processing.
-Operation steps in w1 core when new command is received.
+Operation steps in w1 core when new command is received
=======================================================
When new message (w1_netlink_msg) is received w1 core detects if it is
@@ -167,7 +179,7 @@ When all commands (w1_netlink_cmd) are processed master device is unlocked
and next w1_netlink_msg header processing started.
-Connector [1] specific documentation.
+Connector [1] specific documentation
====================================
Each connector message includes two u32 fields as "address".
@@ -180,10 +192,11 @@ Sequence number for reply is the same as was in request, and
acknowledge number is set to seq+1.
-Additional documantion, source code examples.
-============================================
+Additional documentation, source code examples
+==============================================
1. Documentation/driver-api/connector.rst
2. http://www.ioremap.net/archive/w1
-This archive includes userspace application w1d.c which uses
-read/write/search commands for all master/slave devices found on the bus.
+
+ This archive includes userspace application w1d.c which uses
+ read/write/search commands for all master/slave devices found on the bus.
--
2.21.0
^ permalink raw reply related [flat|nested] 14+ messages in thread
* [PATCH 5/5] docs: spi: convert to ReST and add it to the kABI bookset
2019-06-28 21:23 [PATCH 0/5] Convert misc-devices, i2c, w1, spi and some markdown files to ReST Mauro Carvalho Chehab
` (3 preceding siblings ...)
2019-06-28 21:23 ` [PATCH 4/5] docs: w1: convert to ReST and add to the kAPI group of docs Mauro Carvalho Chehab
@ 2019-06-28 21:23 ` Mauro Carvalho Chehab
2019-07-14 16:24 ` Jonathan Cameron
4 siblings, 1 reply; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 21:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, linux-spi, linux-iio
While there's one file there with briefily describes the uAPI,
the documentation was written just like most subsystems: focused
on kernel developers. So, add it together with driver-api books.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
.../spi/{butterfly => butterfly.rst} | 44 ++++----
Documentation/spi/index.rst | 23 ++++
Documentation/spi/{pxa2xx => pxa2xx.rst} | 94 ++++++++--------
.../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 ++-
.../spi/{spi-sc18is602 => spi-sc18is602.rst} | 3 +
.../spi/{spi-summary => spi-summary.rst} | 103 ++++++++++--------
Documentation/spi/{spidev => spidev.rst} | 30 +++--
drivers/iio/dummy/iio_simple_dummy.c | 2 +-
drivers/spi/Kconfig | 2 +-
drivers/spi/spi-butterfly.c | 2 +-
drivers/spi/spi-lm70llp.c | 2 +-
include/linux/platform_data/sc18is602.h | 2 +-
13 files changed, 198 insertions(+), 127 deletions(-)
rename Documentation/spi/{butterfly => butterfly.rst} (71%)
create mode 100644 Documentation/spi/index.rst
rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (97%)
rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
rename Documentation/spi/{spidev => spidev.rst} (90%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 38ece18f5d1e..bcaddbfa817f 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -115,6 +115,7 @@ needed).
power/index
target/index
timers/index
+ spi/index
w1/index
watchdog/index
input/index
diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly.rst
similarity index 71%
rename from Documentation/spi/butterfly
rename to Documentation/spi/butterfly.rst
index 9927af7a629c..e614a589547c 100644
--- a/Documentation/spi/butterfly
+++ b/Documentation/spi/butterfly.rst
@@ -1,3 +1,4 @@
+===================================================
spi_butterfly - parport-to-butterfly adapter driver
===================================================
@@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP"
connector pins (used also on non-Butterfly AVR boards). On the parport
side this is like "sp12" programming cables.
+ ====== ============= ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- SCK = J403.PB1/SCK = pin 2/D0
- RESET = J403.nRST = pin 3/D1
- VCC = J403.VCC_EXT = pin 8/D6
- MOSI = J403.PB2/MOSI = pin 9/D7
- MISO = J403.PB3/MISO = pin 11/S7,nBUSY
- GND = J403.GND = pin 23/GND
+ ====== ============= ===================
+ SCK J403.PB1/SCK pin 2/D0
+ RESET J403.nRST pin 3/D1
+ VCC J403.VCC_EXT pin 8/D6
+ MOSI J403.PB2/MOSI pin 9/D7
+ MISO J403.PB3/MISO pin 11/S7,nBUSY
+ GND J403.GND pin 23/GND
+ ====== ============= ===================
Then to let Linux master that bus to talk to the DataFlash chip, you must
(a) flash new firmware that disables SPI (set PRR.2, and disable pullups
by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and
(c) cable in the chipselect.
+ ====== ============ ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- VCC = J400.VCC_EXT = pin 7/D5
- SELECT = J400.PB0/nSS = pin 17/C3,nSELECT
- GND = J400.GND = pin 24/GND
+ ====== ============ ===================
+ VCC J400.VCC_EXT pin 7/D5
+ SELECT J400.PB0/nSS pin 17/C3,nSELECT
+ GND J400.GND pin 24/GND
+ ====== ============ ===================
Or you could flash firmware making the AVR into an SPI slave (keeping the
DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
@@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware,
while letting either Linux or the AVR use the DataFlash. There are plenty
of spare parport pins to wire this one up, such as:
+ ====== ============= ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- SCK = J403.PE4/USCK = pin 5/D3
- MOSI = J403.PE5/DI = pin 6/D4
- MISO = J403.PE6/DO = pin 12/S5,nPAPEROUT
- GND = J403.GND = pin 22/GND
-
- IRQ = J402.PF4 = pin 10/S6,ACK
- GND = J402.GND(P2) = pin 25/GND
+ ====== ============= ===================
+ SCK J403.PE4/USCK pin 5/D3
+ MOSI J403.PE5/DI pin 6/D4
+ MISO J403.PE6/DO pin 12/S5,nPAPEROUT
+ GND J403.GND pin 22/GND
+ IRQ J402.PF4 pin 10/S6,ACK
+ GND J402.GND(P2) pin 25/GND
+ ====== ============= ===================
diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
new file mode 100644
index 000000000000..bad6259a7bb6
--- /dev/null
+++ b/Documentation/spi/index.rst
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Serial Peripheral Interface (SPI)
+=================================
+
+.. toctree::
+ :maxdepth: 1
+
+ spi-summary
+ spidev
+ butterfly
+ pxa2xx
+ spi-lm70llp
+ spi-sc18is602
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
+
diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx.rst
similarity index 83%
rename from Documentation/spi/pxa2xx
rename to Documentation/spi/pxa2xx.rst
index 551325b66b23..457faef8be74 100644
--- a/Documentation/spi/pxa2xx
+++ b/Documentation/spi/pxa2xx.rst
@@ -1,8 +1,10 @@
+==============================
PXA2xx SPI on SSP driver HOWTO
-===================================================
+==============================
+
This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx
synchronous serial port into a SPI master controller
-(see Documentation/spi/spi-summary). The driver has the following features
+(see Documentation/spi/spi-summary.rst). The driver has the following features
- Support for any PXA2xx SSP
- SSP PIO and SSP DMA data transfers.
@@ -19,12 +21,12 @@ Declaring PXA2xx Master Controllers
-----------------------------------
Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a
"platform device". The master configuration is passed to the driver via a table
-found in include/linux/spi/pxa2xx_spi.h:
+found in include/linux/spi/pxa2xx_spi.h::
-struct pxa2xx_spi_controller {
+ struct pxa2xx_spi_controller {
u16 num_chipselect;
u8 enable_dma;
-};
+ };
The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
slave device (chips) attached to this SPI master.
@@ -36,9 +38,9 @@ See the "PXA2xx Developer Manual" section "DMA Controller".
NSSP MASTER SAMPLE
------------------
-Below is a sample configuration using the PXA255 NSSP.
+Below is a sample configuration using the PXA255 NSSP::
-static struct resource pxa_spi_nssp_resources[] = {
+ static struct resource pxa_spi_nssp_resources[] = {
[0] = {
.start = __PREG(SSCR0_P(2)), /* Start address of NSSP */
.end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
@@ -49,14 +51,14 @@ static struct resource pxa_spi_nssp_resources[] = {
.end = IRQ_NSSP,
.flags = IORESOURCE_IRQ,
},
-};
+ };
-static struct pxa2xx_spi_controller pxa_nssp_master_info = {
+ static struct pxa2xx_spi_controller pxa_nssp_master_info = {
.num_chipselect = 1, /* Matches the number of chips attached to NSSP */
.enable_dma = 1, /* Enables NSSP DMA */
-};
+ };
-static struct platform_device pxa_spi_nssp = {
+ static struct platform_device pxa_spi_nssp = {
.name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
.id = 2, /* Bus number, MUST MATCH SSP number 1..n */
.resource = pxa_spi_nssp_resources,
@@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = {
.dev = {
.platform_data = &pxa_nssp_master_info, /* Passed to driver */
},
-};
+ };
-static struct platform_device *devices[] __initdata = {
+ static struct platform_device *devices[] __initdata = {
&pxa_spi_nssp,
-};
+ };
-static void __init board_init(void)
-{
+ static void __init board_init(void)
+ {
(void)platform_add_device(devices, ARRAY_SIZE(devices));
-}
+ }
Declaring Slave Devices
-----------------------
Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
using the "spi_board_info" structure found in "linux/spi/spi.h". See
-"Documentation/spi/spi-summary" for additional information.
+"Documentation/spi/spi-summary.rst" for additional information.
Each slave device attached to the PXA must provide slave specific configuration
information via the structure "pxa2xx_spi_chip" found in
@@ -87,19 +89,21 @@ information via the structure "pxa2xx_spi_chip" found in
will uses the configuration whenever the driver communicates with the slave
device. All fields are optional.
-struct pxa2xx_spi_chip {
+::
+
+ struct pxa2xx_spi_chip {
u8 tx_threshold;
u8 rx_threshold;
u8 dma_burst_size;
u32 timeout;
u8 enable_loopback;
void (*cs_control)(u32 command);
-};
+ };
The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
used to configure the SSP hardware fifo. These fields are critical to the
performance of pxa2xx_spi driver and misconfiguration will result in rx
-fifo overruns (especially in PIO mode transfers). Good default values are
+fifo overruns (especially in PIO mode transfers). Good default values are::
.tx_threshold = 8,
.rx_threshold = 8,
@@ -141,41 +145,43 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
"spi_board_info.controller_data" field. Below is a sample configuration using
the PXA255 NSSP.
-/* Chip Select control for the CS8415A SPI slave device */
-static void cs8415a_cs_control(u32 command)
-{
+::
+
+ /* Chip Select control for the CS8415A SPI slave device */
+ static void cs8415a_cs_control(u32 command)
+ {
if (command & PXA2XX_CS_ASSERT)
GPCR(2) = GPIO_bit(2);
else
GPSR(2) = GPIO_bit(2);
-}
+ }
-/* Chip Select control for the CS8405A SPI slave device */
-static void cs8405a_cs_control(u32 command)
-{
+ /* Chip Select control for the CS8405A SPI slave device */
+ static void cs8405a_cs_control(u32 command)
+ {
if (command & PXA2XX_CS_ASSERT)
GPCR(3) = GPIO_bit(3);
else
GPSR(3) = GPIO_bit(3);
-}
+ }
-static struct pxa2xx_spi_chip cs8415a_chip_info = {
+ static struct pxa2xx_spi_chip cs8415a_chip_info = {
.tx_threshold = 8, /* SSP hardward FIFO threshold */
.rx_threshold = 8, /* SSP hardward FIFO threshold */
.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
.timeout = 235, /* See Intel documentation */
.cs_control = cs8415a_cs_control, /* Use external chip select */
-};
+ };
-static struct pxa2xx_spi_chip cs8405a_chip_info = {
+ static struct pxa2xx_spi_chip cs8405a_chip_info = {
.tx_threshold = 8, /* SSP hardward FIFO threshold */
.rx_threshold = 8, /* SSP hardward FIFO threshold */
.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
.timeout = 235, /* See Intel documentation */
.cs_control = cs8405a_cs_control, /* Use external chip select */
-};
+ };
-static struct spi_board_info streetracer_spi_board_info[] __initdata = {
+ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
{
.modalias = "cs8415a", /* Name of spi_driver for this device */
.max_speed_hz = 3686400, /* Run SSP as fast a possbile */
@@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
.controller_data = &cs8405a_chip_info, /* Master chip config */
.irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
},
-};
+ };
-static void __init streetracer_init(void)
-{
+ static void __init streetracer_init(void)
+ {
spi_register_board_info(streetracer_spi_board_info,
ARRAY_SIZE(streetracer_spi_board_info));
-}
+ }
DMA and PIO I/O Support
@@ -210,22 +216,22 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The
mode supports both coherent and stream based DMA mappings.
The following logic is used to determine the type of I/O to be used on
-a per "spi_transfer" basis:
+a per "spi_transfer" basis::
-if !enable_dma then
+ if !enable_dma then
always use PIO transfers
-if spi_message.len > 8191 then
+ if spi_message.len > 8191 then
print "rate limited" warning
use PIO transfers
-if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
+ if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
use coherent DMA mode
-if rx_buf and tx_buf are aligned on 8 byte boundary then
+ if rx_buf and tx_buf are aligned on 8 byte boundary then
use streaming DMA mode
-otherwise
+ otherwise
use PIO transfer
THANKS TO
diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp.rst
similarity index 88%
rename from Documentation/spi/spi-lm70llp
rename to Documentation/spi/spi-lm70llp.rst
index 463f6d01fa15..07631aef4343 100644
--- a/Documentation/spi/spi-lm70llp
+++ b/Documentation/spi/spi-lm70llp.rst
@@ -1,8 +1,11 @@
+==============================================
spi_lm70llp : LM70-LLP parport-to-SPI adapter
==============================================
Supported board/chip:
+
* National Semiconductor LM70 LLP evaluation board
+
Datasheet: http://www.national.com/pf/LM/LM70.html
Author:
@@ -29,9 +32,10 @@ available (on page 4) here:
The hardware interfacing on the LM70 LLP eval board is as follows:
+ ======== == ========= ==========
Parallel LM70 LLP
- Port Direction JP2 Header
- ----------- --------- ----------------
+ Port . Direction JP2 Header
+ ======== == ========= ==========
D0 2 - -
D1 3 --> V+ 5
D2 4 --> V+ 5
@@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows:
D7 9 --> SI/O 5
GND 25 - GND 7
Select 13 <-- SI/O 1
- ----------- --------- ----------------
+ ======== == ========= ==========
Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
is connected to both pin D7 (as Master Out) and Select (as Master In)
@@ -74,6 +78,7 @@ inverting the value read at pin 13.
Thanks to
---------
-o David Brownell for mentoring the SPI-side driver development.
-o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
-o Nadir Billimoria for help interpreting the circuit schematic.
+
+- David Brownell for mentoring the SPI-side driver development.
+- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
+- Nadir Billimoria for help interpreting the circuit schematic.
diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602.rst
similarity index 97%
rename from Documentation/spi/spi-sc18is602
rename to Documentation/spi/spi-sc18is602.rst
index 0feffd5af411..2a31dc722321 100644
--- a/Documentation/spi/spi-sc18is602
+++ b/Documentation/spi/spi-sc18is602.rst
@@ -1,8 +1,11 @@
+===========================
Kernel driver spi-sc18is602
===========================
Supported chips:
+
* NXP SI18IS602/602B/603
+
Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
Author:
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary.rst
similarity index 93%
rename from Documentation/spi/spi-summary
rename to Documentation/spi/spi-summary.rst
index 1a63194b74d7..96b3f8b8b3db 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary.rst
@@ -1,3 +1,4 @@
+====================================
Overview of Linux kernel SPI support
====================================
@@ -139,12 +140,14 @@ a command and then reading its response.
There are two types of SPI driver, here called:
- Controller drivers ... controllers may be built into System-On-Chip
+ Controller drivers ...
+ controllers may be built into System-On-Chip
processors, and often support both Master and Slave roles.
These drivers touch hardware registers and may use DMA.
Or they can be PIO bitbangers, needing just GPIO pins.
- Protocol drivers ... these pass messages through the controller
+ Protocol drivers ...
+ these pass messages through the controller
driver to communicate with a Slave or Master device on the
other side of an SPI link.
@@ -160,7 +163,7 @@ those two types of drivers.
There is a minimal core of SPI programming interfaces, focussing on
using the driver model to connect controller and protocol drivers using
device tables provided by board specific initialization code. SPI
-shows up in sysfs in several locations:
+shows up in sysfs in several locations::
/sys/devices/.../CTLR ... physical node for a given SPI controller
@@ -206,7 +209,8 @@ Linux needs several kinds of information to properly configure SPI devices.
That information is normally provided by board-specific code, even for
chips that do support some of automated discovery/enumeration.
-DECLARE CONTROLLERS
+Declare Controllers
+^^^^^^^^^^^^^^^^^^^
The first kind of information is a list of what SPI controllers exist.
For System-on-Chip (SOC) based boards, these will usually be platform
@@ -221,7 +225,7 @@ same basic controller setup code. This is because most SOCs have several
SPI-capable controllers, and only the ones actually usable on a given
board should normally be set up and registered.
-So for example arch/.../mach-*/board-*.c files might have code like:
+So for example arch/.../mach-*/board-*.c files might have code like::
#include <mach/spi.h> /* for mysoc_spi_data */
@@ -238,7 +242,7 @@ So for example arch/.../mach-*/board-*.c files might have code like:
...
}
-And SOC-specific utility code might look something like:
+And SOC-specific utility code might look something like::
#include <mach/spi.h>
@@ -269,8 +273,8 @@ same SOC controller is used. For example, on one board SPI might use
an external clock, where another derives the SPI clock from current
settings of some master clock.
-
-DECLARE SLAVE DEVICES
+Declare Slave Devices
+^^^^^^^^^^^^^^^^^^^^^
The second kind of information is a list of what SPI slave devices exist
on the target board, often with some board-specific data needed for the
@@ -278,7 +282,7 @@ driver to work correctly.
Normally your arch/.../mach-*/board-*.c files would provide a small table
listing the SPI devices on each board. (This would typically be only a
-small handful.) That might look like:
+small handful.) That might look like::
static struct ads7846_platform_data ads_info = {
.vref_delay_usecs = 100,
@@ -316,7 +320,7 @@ not possible until the infrastructure knows how to deselect it.
Then your board initialization code would register that table with the SPI
infrastructure, so that it's available later when the SPI master controller
-driver is registered:
+driver is registered::
spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
@@ -324,12 +328,13 @@ Like with other static board-specific setup, you won't unregister those.
The widely used "card" style computers bundle memory, cpu, and little else
onto a card that's maybe just thirty square centimeters. On such systems,
-your arch/.../mach-.../board-*.c file would primarily provide information
+your ``arch/.../mach-.../board-*.c`` file would primarily provide information
about the devices on the mainboard into which such a card is plugged. That
certainly includes SPI devices hooked up through the card connectors!
-NON-STATIC CONFIGURATIONS
+Non-static Configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^
Developer boards often play by different rules than product boards, and one
example is the potential need to hotplug SPI devices and/or controllers.
@@ -349,7 +354,7 @@ How do I write an "SPI Protocol Driver"?
Most SPI drivers are currently kernel drivers, but there's also support
for userspace drivers. Here we talk only about kernel drivers.
-SPI protocol drivers somewhat resemble platform device drivers:
+SPI protocol drivers somewhat resemble platform device drivers::
static struct spi_driver CHIP_driver = {
.driver = {
@@ -367,6 +372,8 @@ device whose board_info gave a modalias of "CHIP". Your probe() code
might look like this unless you're creating a device which is managing
a bus (appearing under /sys/class/spi_master).
+::
+
static int CHIP_probe(struct spi_device *spi)
{
struct CHIP *chip;
@@ -479,6 +486,8 @@ The main task of this type of driver is to provide an "spi_master".
Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
to get the driver-private data allocated for that device.
+::
+
struct spi_master *master;
struct CONTROLLER *c;
@@ -503,7 +512,8 @@ If you need to remove your SPI controller driver, spi_unregister_master()
will reverse the effect of spi_register_master().
-BUS NUMBERING
+Bus Numbering
+^^^^^^^^^^^^^
Bus numbering is important, since that's how Linux identifies a given
SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
@@ -517,9 +527,10 @@ then be replaced by a dynamically assigned number. You'd then need to treat
this as a non-static configuration (see above).
-SPI MASTER METHODS
+SPI Master Methods
+^^^^^^^^^^^^^^^^^^
- master->setup(struct spi_device *spi)
+``master->setup(struct spi_device *spi)``
This sets up the device clock rate, SPI mode, and word sizes.
Drivers may change the defaults provided by board_info, and then
call spi_setup(spi) to invoke this routine. It may sleep.
@@ -528,37 +539,37 @@ SPI MASTER METHODS
change them right away ... otherwise drivers could corrupt I/O
that's in progress for other SPI devices.
- ** BUG ALERT: for some reason the first version of
- ** many spi_master drivers seems to get this wrong.
- ** When you code setup(), ASSUME that the controller
- ** is actively processing transfers for another device.
+ .. note::
- master->cleanup(struct spi_device *spi)
+ BUG ALERT: for some reason the first version of
+ many spi_master drivers seems to get this wrong.
+ When you code setup(), ASSUME that the controller
+ is actively processing transfers for another device.
+
+``master->cleanup(struct spi_device *spi)``
Your controller driver may use spi_device.controller_state to hold
state it dynamically associates with that device. If you do that,
be sure to provide the cleanup() method to free that state.
- master->prepare_transfer_hardware(struct spi_master *master)
+``master->prepare_transfer_hardware(struct spi_master *master)``
This will be called by the queue mechanism to signal to the driver
that a message is coming in soon, so the subsystem requests the
driver to prepare the transfer hardware by issuing this call.
This may sleep.
- master->unprepare_transfer_hardware(struct spi_master *master)
+``master->unprepare_transfer_hardware(struct spi_master *master)``
This will be called by the queue mechanism to signal to the driver
that there are no more messages pending in the queue and it may
relax the hardware (e.g. by power management calls). This may sleep.
- master->transfer_one_message(struct spi_master *master,
- struct spi_message *mesg)
+``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
The subsystem calls the driver to transfer a single message while
queuing transfers that arrive in the meantime. When the driver is
finished with this message, it must call
spi_finalize_current_message() so the subsystem can issue the next
message. This may sleep.
- master->transfer_one(struct spi_master *master, struct spi_device *spi,
- struct spi_transfer *transfer)
+``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
The subsystem calls the driver to transfer a single transfer while
queuing transfers that arrive in the meantime. When the driver is
finished with this transfer, it must call
@@ -568,19 +579,20 @@ SPI MASTER METHODS
not call your transfer_one callback.
Return values:
- negative errno: error
- 0: transfer is finished
- 1: transfer is still in progress
- master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles,
- u8 hold_clk_cycles, u8 inactive_clk_cycles)
+ * negative errno: error
+ * 0: transfer is finished
+ * 1: transfer is still in progress
+
+``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
This method allows SPI client drivers to request SPI master controller
for configuring device specific CS setup, hold and inactive timing
requirements.
- DEPRECATED METHODS
+Deprecated Methods
+^^^^^^^^^^^^^^^^^^
- master->transfer(struct spi_device *spi, struct spi_message *message)
+``master->transfer(struct spi_device *spi, struct spi_message *message)``
This must not sleep. Its responsibility is to arrange that the
transfer happens and its complete() callback is issued. The two
will normally happen later, after other transfers complete, and
@@ -590,7 +602,8 @@ SPI MASTER METHODS
implemented.
-SPI MESSAGE QUEUE
+SPI Message Queue
+^^^^^^^^^^^^^^^^^
If you are happy with the standard queueing mechanism provided by the
SPI subsystem, just implement the queued methods specified above. Using
@@ -619,13 +632,13 @@ THANKS TO
Contributors to Linux-SPI discussions include (in alphabetical order,
by last name):
-Mark Brown
-David Brownell
-Russell King
-Grant Likely
-Dmitry Pervushin
-Stephen Street
-Mark Underwood
-Andrew Victor
-Linus Walleij
-Vitaly Wool
+- Mark Brown
+- David Brownell
+- Russell King
+- Grant Likely
+- Dmitry Pervushin
+- Stephen Street
+- Mark Underwood
+- Andrew Victor
+- Linus Walleij
+- Vitaly Wool
diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev.rst
similarity index 90%
rename from Documentation/spi/spidev
rename to Documentation/spi/spidev.rst
index 3d14035b1766..f05dbc5ccdbc 100644
--- a/Documentation/spi/spidev
+++ b/Documentation/spi/spidev.rst
@@ -1,7 +1,13 @@
+=================
+SPI userspace API
+=================
+
SPI devices have a limited userspace API, supporting basic half-duplex
read() and write() access to SPI slave devices. Using ioctl() requests,
full duplex transfers and device I/O configuration are also available.
+::
+
#include <fcntl.h>
#include <unistd.h>
#include <sys/ioctl.h>
@@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev.
busybox; it's less featureful, but often enough.) For a SPI device with
chipselect C on bus B, you should see:
- /dev/spidevB.C ... character special device, major number 153 with
+ /dev/spidevB.C ...
+ character special device, major number 153 with
a dynamically chosen minor device number. This is the node
that userspace programs will open, created by "udev" or "mdev".
- /sys/devices/.../spiB.C ... as usual, the SPI device node will
+ /sys/devices/.../spiB.C ...
+ as usual, the SPI device node will
be a child of its SPI master controller.
- /sys/class/spidev/spidevB.C ... created when the "spidev" driver
+ /sys/class/spidev/spidevB.C ...
+ created when the "spidev" driver
binds to that device. (Directory or symlink, based on whether
or not you enabled the "deprecated sysfs files" Kconfig option.)
@@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request.
Several ioctl() requests let your driver read or override the device's current
settings for data transfer parameters:
- SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
+ SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
+ pass a pointer to a byte which will
return (RD) or assign (WR) the SPI transfer mode. Use the constants
SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
(clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
@@ -88,22 +98,26 @@ settings for data transfer parameters:
Note that this request is limited to SPI mode flags that fit in a
single byte.
- SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
+ SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
+ pass a pointer to a uin32_t
which will return (RD) or assign (WR) the full SPI transfer mode,
not limited to the bits that fit in one byte.
- SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
+ SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
+ pass a pointer to a byte
which will return (RD) or assign (WR) the bit justification used to
transfer SPI words. Zero indicates MSB-first; other values indicate
the less common LSB-first encoding. In both cases the specified value
is right-justified in each word, so that unused (TX) or undefined (RX)
bits are in the MSBs.
- SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
+ SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
+ pass a pointer to
a byte which will return (RD) or assign (WR) the number of bits in
each SPI transfer word. The value zero signifies eight bits.
- SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
+ SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
+ pass a pointer to a
u32 which will return (RD) or assign (WR) the maximum SPI transfer
speed, in Hz. The controller can't necessarily assign that specific
clock speed.
diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
index d28974ad9e0e..6cb02299a215 100644
--- a/drivers/iio/dummy/iio_simple_dummy.c
+++ b/drivers/iio/dummy/iio_simple_dummy.c
@@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
* i2c:
* Documentation/i2c/writing-clients.rst
* spi:
- * Documentation/spi/spi-summary
+ * Documentation/spi/spi-summary.rst
*/
static const struct iio_sw_device_ops iio_dummy_device_ops = {
.probe = iio_dummy_probe,
diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig
index 3a1d8f1170de..d5a24fe983e7 100644
--- a/drivers/spi/Kconfig
+++ b/drivers/spi/Kconfig
@@ -543,7 +543,7 @@ config SPI_PXA2XX
help
This enables using a PXA2xx or Sodaville SSP port as a SPI master
controller. The driver can be configured to use any SSP port and
- additional documentation can be found a Documentation/spi/pxa2xx.
+ additional documentation can be found a Documentation/spi/pxa2xx.rst.
config SPI_PXA2XX_PCI
def_tristate SPI_PXA2XX && PCI && COMMON_CLK
diff --git a/drivers/spi/spi-butterfly.c b/drivers/spi/spi-butterfly.c
index 8c77d1114ad3..7e71a351f3b7 100644
--- a/drivers/spi/spi-butterfly.c
+++ b/drivers/spi/spi-butterfly.c
@@ -23,7 +23,7 @@
* with a battery powered AVR microcontroller and lots of goodies. You
* can use GCC to develop firmware for this.
*
- * See Documentation/spi/butterfly for information about how to build
+ * See Documentation/spi/butterfly.rst for information about how to build
* and use this custom parallel port cable.
*/
diff --git a/drivers/spi/spi-lm70llp.c b/drivers/spi/spi-lm70llp.c
index f18f912c9dea..174dba29b1dd 100644
--- a/drivers/spi/spi-lm70llp.c
+++ b/drivers/spi/spi-lm70llp.c
@@ -34,7 +34,7 @@
* available (on page 4) here:
* http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
*
- * Also see Documentation/spi/spi-lm70llp. The SPI<->parport code here is
+ * Also see Documentation/spi/spi-lm70llp.rst. The SPI<->parport code here is
* (heavily) based on spi-butterfly by David Brownell.
*
* The LM70 LLP connects to the PC parallel port in the following manner:
diff --git a/include/linux/platform_data/sc18is602.h b/include/linux/platform_data/sc18is602.h
index e066d3b0d6d8..0e91489edfe6 100644
--- a/include/linux/platform_data/sc18is602.h
+++ b/include/linux/platform_data/sc18is602.h
@@ -4,7 +4,7 @@
*
* Copyright (C) 2012 Guenter Roeck <linux@roeck-us.net>
*
- * For further information, see the Documentation/spi/spi-sc18is602 file.
+ * For further information, see the Documentation/spi/spi-sc18is602.rst file.
*/
/**
--
2.21.0
^ permalink raw reply related [flat|nested] 14+ messages in thread
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
2019-06-28 21:23 ` [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset Mauro Carvalho Chehab
@ 2019-06-28 21:41 ` Alexandre Belloni
2019-06-28 21:54 ` Mauro Carvalho Chehab
2019-06-29 10:57 ` Wolfram Sang
` (2 subsequent siblings)
3 siblings, 1 reply; 14+ messages in thread
From: Alexandre Belloni @ 2019-06-28 21:41 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, Alessandro Zummo,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
On 28/06/2019 18:23:14-0300, Mauro Carvalho Chehab wrote:
> diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
> index 225a8df1d4e9..1803f3cab39f 100644
> --- a/drivers/rtc/rtc-ds1374.c
> +++ b/drivers/rtc/rtc-ds1374.c
> @@ -14,7 +14,7 @@
> */
> /*
> * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
> - * recommened in .../Documentation/i2c/writing-clients section
> + * recommened in .../Documentation/i2c/writing-clients.rst section
> * "Sending and receiving", using SMBus level communication is preferred.
> */
>
Honestly, the whole comment could be removed. The current trend is to
move everything to regmap anyway.
However, I'm fine with that change if you want to keep it that way (and
probably scripted).
--
Alexandre Belloni, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
2019-06-28 21:41 ` Alexandre Belloni
@ 2019-06-28 21:54 ` Mauro Carvalho Chehab
2019-06-28 22:10 ` Alexandre Belloni
0 siblings, 1 reply; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 21:54 UTC (permalink / raw)
To: Alexandre Belloni
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, Alessandro Zummo,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
Em Fri, 28 Jun 2019 23:41:38 +0200
Alexandre Belloni <alexandre.belloni@bootlin.com> escreveu:
> On 28/06/2019 18:23:14-0300, Mauro Carvalho Chehab wrote:
> > diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
> > index 225a8df1d4e9..1803f3cab39f 100644
> > --- a/drivers/rtc/rtc-ds1374.c
> > +++ b/drivers/rtc/rtc-ds1374.c
> > @@ -14,7 +14,7 @@
> > */
> > /*
> > * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
> > - * recommened in .../Documentation/i2c/writing-clients section
> > + * recommened in .../Documentation/i2c/writing-clients.rst section
> > * "Sending and receiving", using SMBus level communication is preferred.
> > */
> >
>
> Honestly, the whole comment could be removed. The current trend is to
> move everything to regmap anyway.
>
> However, I'm fine with that change if you want to keep it that way (and
> probably scripted).
While the conversion was manually made, the renames were scripted,
and checked with:
./scripts/documentation-file-ref-check
Otherwise I would very likely fix the typo:
recommened -> recommended
:-)
I can certainly add new patch at this (before or after patch 3/5 - as you
prefer) in order to get rid of the comment, but I would avoid doing a
somewhat unrelated changes at the same documentation patch.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
2019-06-28 21:54 ` Mauro Carvalho Chehab
@ 2019-06-28 22:10 ` Alexandre Belloni
0 siblings, 0 replies; 14+ messages in thread
From: Alexandre Belloni @ 2019-06-28 22:10 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, Alessandro Zummo,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
On 28/06/2019 18:54:45-0300, Mauro Carvalho Chehab wrote:
> Em Fri, 28 Jun 2019 23:41:38 +0200
> Alexandre Belloni <alexandre.belloni@bootlin.com> escreveu:
>
> > On 28/06/2019 18:23:14-0300, Mauro Carvalho Chehab wrote:
> > > diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
> > > index 225a8df1d4e9..1803f3cab39f 100644
> > > --- a/drivers/rtc/rtc-ds1374.c
> > > +++ b/drivers/rtc/rtc-ds1374.c
> > > @@ -14,7 +14,7 @@
> > > */
> > > /*
> > > * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
> > > - * recommened in .../Documentation/i2c/writing-clients section
> > > + * recommened in .../Documentation/i2c/writing-clients.rst section
> > > * "Sending and receiving", using SMBus level communication is preferred.
> > > */
> > >
> >
> > Honestly, the whole comment could be removed. The current trend is to
> > move everything to regmap anyway.
> >
> > However, I'm fine with that change if you want to keep it that way (and
> > probably scripted).
>
> While the conversion was manually made, the renames were scripted,
> and checked with:
>
> ./scripts/documentation-file-ref-check
>
> Otherwise I would very likely fix the typo:
>
> recommened -> recommended
>
> :-)
>
> I can certainly add new patch at this (before or after patch 3/5 - as you
> prefer) in order to get rid of the comment, but I would avoid doing a
> somewhat unrelated changes at the same documentation patch.
>
I'm okay with that.
--
Alexandre Belloni, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 1/5] docs: convert markdown documents to ReST
2019-06-28 21:23 ` [PATCH 1/5] docs: convert markdown documents " Mauro Carvalho Chehab
@ 2019-06-28 22:38 ` Rob Herring
0 siblings, 0 replies; 14+ messages in thread
From: Rob Herring @ 2019-06-28 22:38 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mark Rutland, devicetree
On Fri, Jun 28, 2019 at 3:23 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> The documentation standard is ReST and not markdown.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/devicetree/writing-schema.md | 130 ---------------
> Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++++++
I wasn't really ever intending to integrate this into the rest of the
kernel docs, but I'm not tied to any format so:
Acked-by: Rob Herring <robh@kernel.org>
> ...entication.md => ubifs-authentication.rst} | 70 +++++---
> 3 files changed, 197 insertions(+), 156 deletions(-)
> delete mode 100644 Documentation/devicetree/writing-schema.md
> create mode 100644 Documentation/devicetree/writing-schema.rst
> rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
2019-06-28 21:23 ` [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset Mauro Carvalho Chehab
2019-06-28 21:41 ` Alexandre Belloni
@ 2019-06-29 10:57 ` Wolfram Sang
2019-06-29 11:37 ` Alexandre Belloni
2019-07-14 16:23 ` Jonathan Cameron
3 siblings, 0 replies; 14+ messages in thread
From: Wolfram Sang @ 2019-06-29 10:57 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Rudolf Marek,
Seth Heasley, Neil Horman, Vadim Pasternak, Michael Shych,
Ajay Gupta, Peter Korsgaard, Andrew Lunn, Jim Cromie, Mark Brown,
Jonathan Cameron, Hartmut Knaack, Lars-Peter Clausen,
Peter Meerwald-Stadler, Alessandro Zummo, Alexandre Belloni,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
[-- Attachment #1: Type: text/plain, Size: 595 bytes --]
On Fri, Jun 28, 2019 at 06:23:14PM -0300, Mauro Carvalho Chehab wrote:
> Convert each file at I2C subsystem, renaming them to .rst and
> adding to the driver-api book.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
I glimpsed over it and it looks basically OK. I won't have time to
actually review all of this. But I trust you and we can fix things
later. So:
Acked-by: Wolfram Sang <wsa@the-dreams.de>
I assume this goes in via your or doc-tree?
> Next/merge.log | 6 +-
This file doesn't exist upstream, though.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
2019-06-28 21:23 ` [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset Mauro Carvalho Chehab
2019-06-28 21:41 ` Alexandre Belloni
2019-06-29 10:57 ` Wolfram Sang
@ 2019-06-29 11:37 ` Alexandre Belloni
2019-07-14 16:23 ` Jonathan Cameron
3 siblings, 0 replies; 14+ messages in thread
From: Alexandre Belloni @ 2019-06-29 11:37 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, Alessandro Zummo,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
On 28/06/2019 18:23:14-0300, Mauro Carvalho Chehab wrote:
> Convert each file at I2C subsystem, renaming them to .rst and
> adding to the driver-api book.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com>
> ---
> Documentation/IPMB.txt | 2 +-
> .../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +-
> Documentation/hwmon/adm1021.rst | 2 +-
> Documentation/hwmon/adm1275.rst | 2 +-
> Documentation/hwmon/hih6130.rst | 2 +-
> Documentation/hwmon/ibm-cffps.rst | 2 +-
> Documentation/hwmon/lm25066.rst | 2 +-
> Documentation/hwmon/max16064.rst | 2 +-
> Documentation/hwmon/max16065.rst | 2 +-
> Documentation/hwmon/max20751.rst | 2 +-
> Documentation/hwmon/max34440.rst | 2 +-
> Documentation/hwmon/max6650.rst | 2 +-
> Documentation/hwmon/max8688.rst | 2 +-
> Documentation/hwmon/menf21bmc.rst | 2 +-
> Documentation/hwmon/pcf8591.rst | 2 +-
> Documentation/hwmon/sht3x.rst | 2 +-
> Documentation/hwmon/shtc1.rst | 2 +-
> Documentation/hwmon/tmp103.rst | 2 +-
> Documentation/hwmon/tps40422.rst | 2 +-
> Documentation/hwmon/ucd9000.rst | 2 +-
> Documentation/hwmon/ucd9200.rst | 2 +-
> Documentation/hwmon/via686a.rst | 2 +-
> Documentation/hwmon/zl6100.rst | 2 +-
> .../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +-
> .../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 +
> .../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 63 +++---
> Documentation/i2c/busses/i2c-amd-mp2 | 23 ---
> Documentation/i2c/busses/i2c-amd-mp2.rst | 25 +++
> .../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +-
> .../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +-
> .../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 +
> .../i2c/busses/{i2c-i801 => i2c-i801.rst} | 31 ++-
> .../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +-
> .../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 +
> .../busses/{i2c-nforce2 => i2c-nforce2.rst} | 23 ++-
> .../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +-
> .../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +-
> Documentation/i2c/busses/i2c-parport | 178 ----------------
> ...2c-parport-light => i2c-parport-light.rst} | 2 +
> Documentation/i2c/busses/i2c-parport.rst | 190 +++++++++++++++++
> .../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +-
> .../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 14 +-
> .../busses/{i2c-sis5595 => i2c-sis5595.rst} | 18 +-
> Documentation/i2c/busses/i2c-sis630 | 58 ------
> Documentation/i2c/busses/i2c-sis630.rst | 64 ++++++
> .../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 28 ++-
> .../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +-
> .../i2c/busses/{i2c-via => i2c-via.rst} | 20 +-
> .../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +-
> Documentation/i2c/busses/index.rst | 33 +++
> .../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +-
> .../i2c/{dev-interface => dev-interface.rst} | 94 +++++----
> ...-considerations => dma-considerations.rst} | 0
> .../i2c/{fault-codes => fault-codes.rst} | 4 +
> .../i2c/{functionality => functionality.rst} | 18 +-
> ...ult-injection => gpio-fault-injection.rst} | 12 +-
> .../i2c/{i2c-protocol => i2c-protocol.rst} | 28 ++-
> Documentation/i2c/{i2c-stub => i2c-stub.rst} | 19 +-
> .../i2c/{i2c-topology => i2c-topology.rst} | 68 +++---
> Documentation/i2c/index.rst | 38 ++++
> ...ting-devices => instantiating-devices.rst} | 45 ++--
> .../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +--
> ...e-parameters => old-module-parameters.rst} | 27 ++-
> ...eprom-backend => slave-eeprom-backend.rst} | 3 +-
> .../{slave-interface => slave-interface.rst} | 32 +--
> .../{smbus-protocol => smbus-protocol.rst} | 74 ++++---
> Documentation/i2c/{summary => summary.rst} | 4 +-
> ...en-bit-addresses => ten-bit-addresses.rst} | 5 +
> ...pgrading-clients => upgrading-clients.rst} | 194 +++++++++---------
> .../{writing-clients => writing-clients.rst} | 94 +++++----
> Documentation/index.rst | 1 +
> Documentation/spi/spi-sc18is602 | 2 +-
> MAINTAINERS | 48 ++---
> Next/merge.log | 6 +-
> drivers/hwmon/atxp1.c | 2 +-
> drivers/hwmon/smm665.c | 2 +-
> drivers/i2c/Kconfig | 4 +-
> drivers/i2c/busses/Kconfig | 2 +-
> drivers/i2c/busses/i2c-i801.c | 2 +-
> drivers/i2c/busses/i2c-taos-evm.c | 2 +-
> drivers/i2c/i2c-core-base.c | 4 +-
> drivers/iio/dummy/iio_simple_dummy.c | 2 +-
> drivers/rtc/rtc-ds1374.c | 2 +-
> include/linux/i2c.h | 2 +-
> 84 files changed, 1065 insertions(+), 750 deletions(-)
> rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
> rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
> rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
> delete mode 100644 Documentation/i2c/busses/i2c-amd-mp2
> create mode 100644 Documentation/i2c/busses/i2c-amd-mp2.rst
> rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
> rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
> rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
> rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
> rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
> rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
> rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (68%)
> rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
> rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
> delete mode 100644 Documentation/i2c/busses/i2c-parport
> rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (92%)
> create mode 100644 Documentation/i2c/busses/i2c-parport.rst
> rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
> rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
> rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
> delete mode 100644 Documentation/i2c/busses/i2c-sis630
> create mode 100644 Documentation/i2c/busses/i2c-sis630.rst
> rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (75%)
> rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
> rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (61%)
> rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
> create mode 100644 Documentation/i2c/busses/index.rst
> rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
> rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
> rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
> rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
> rename Documentation/i2c/{functionality => functionality.rst} (91%)
> rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
> rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
> rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
> rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
> create mode 100644 Documentation/i2c/index.rst
> rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
> rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
> rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
> rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
> rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
> rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (84%)
> rename Documentation/i2c/{summary => summary.rst} (96%)
> rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
> rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (56%)
> rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
>
> diff --git a/Documentation/IPMB.txt b/Documentation/IPMB.txt
> index a6ed8b68bd0f..cd20c9764705 100644
> --- a/Documentation/IPMB.txt
> +++ b/Documentation/IPMB.txt
> @@ -82,7 +82,7 @@ Instantiate the device
> ----------------------
>
> After loading the driver, you can instantiate the device as
> -described in 'Documentation/i2c/instantiating-devices'.
> +described in 'Documentation/i2c/instantiating-devices.rst'.
> If you have multiple BMCs, each connected to your Satellite MC via
> a different I2C bus, you can instantiate a device for each of
> those BMCs.
> diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
> index 2907dab56298..8b444b94e92f 100644
> --- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
> +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
> @@ -42,7 +42,7 @@ Optional properties:
> This means that no unrelated I2C transactions are allowed on the parent I2C
> adapter for the complete multiplexed I2C transaction.
> The properties of mux-locked and parent-locked multiplexers are discussed
> - in more detail in Documentation/i2c/i2c-topology.
> + in more detail in Documentation/i2c/i2c-topology.rst.
>
> For each i2c child node, an I2C child bus will be created. They will
> be numbered based on their order in the device tree.
> diff --git a/Documentation/hwmon/adm1021.rst b/Documentation/hwmon/adm1021.rst
> index 6cbb0f75fe00..116fb2019956 100644
> --- a/Documentation/hwmon/adm1021.rst
> +++ b/Documentation/hwmon/adm1021.rst
> @@ -142,7 +142,7 @@ loading the adm1021 module, then things are good.
> If nothing happens when loading the adm1021 module, and you are certain
> that your specific Xeon processor model includes compatible sensors, you
> will have to explicitly instantiate the sensor chips from user-space. See
> -method 4 in Documentation/i2c/instantiating-devices. Possible slave
> +method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave
> addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that
> only temp2 will be correct and temp1 will have to be ignored.
>
> diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst
> index 9a1913e5b4d9..49966ed70ec6 100644
> --- a/Documentation/hwmon/adm1275.rst
> +++ b/Documentation/hwmon/adm1275.rst
> @@ -75,7 +75,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> The ADM1075, unlike many other PMBus devices, does not support internal voltage
> diff --git a/Documentation/hwmon/hih6130.rst b/Documentation/hwmon/hih6130.rst
> index 649bd4be4fc2..e95d373eb693 100644
> --- a/Documentation/hwmon/hih6130.rst
> +++ b/Documentation/hwmon/hih6130.rst
> @@ -27,7 +27,7 @@ The devices communicate with the I2C protocol. All sensors are set to the same
> I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27)
> can be used in the board setup code.
>
> -Please see Documentation/i2c/instantiating-devices for details on how to
> +Please see Documentation/i2c/instantiating-devices.rst for details on how to
> instantiate I2C devices.
>
> sysfs-Interface
> diff --git a/Documentation/hwmon/ibm-cffps.rst b/Documentation/hwmon/ibm-cffps.rst
> index 52e74e39463a..ef8f3f806968 100644
> --- a/Documentation/hwmon/ibm-cffps.rst
> +++ b/Documentation/hwmon/ibm-cffps.rst
> @@ -17,7 +17,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> Sysfs entries
> diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst
> index da15e3094c8c..30e6e77fb3c8 100644
> --- a/Documentation/hwmon/lm25066.rst
> +++ b/Documentation/hwmon/lm25066.rst
> @@ -76,7 +76,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/max16064.rst b/Documentation/hwmon/max16064.rst
> index 6d5e9538991f..c06249292557 100644
> --- a/Documentation/hwmon/max16064.rst
> +++ b/Documentation/hwmon/max16064.rst
> @@ -28,7 +28,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/max16065.rst b/Documentation/hwmon/max16065.rst
> index fa5c852a178c..45f69f334f25 100644
> --- a/Documentation/hwmon/max16065.rst
> +++ b/Documentation/hwmon/max16065.rst
> @@ -79,7 +79,7 @@ Usage Notes
>
> This driver does not probe for devices, since there is no register which
> can be safely used to identify the chip. You will have to instantiate
> -the devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> WARNING: Do not access chip registers using the i2cdump command, and do not use
> diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst
> index aa4469be6674..fe701e07eaf5 100644
> --- a/Documentation/hwmon/max20751.rst
> +++ b/Documentation/hwmon/max20751.rst
> @@ -30,7 +30,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst
> index 939138e12b02..5744df100a5d 100644
> --- a/Documentation/hwmon/max34440.rst
> +++ b/Documentation/hwmon/max34440.rst
> @@ -83,7 +83,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> For MAX34446, the value of the currX_crit attribute determines if current or
> diff --git a/Documentation/hwmon/max6650.rst b/Documentation/hwmon/max6650.rst
> index 253482add082..7952b6ecaa2d 100644
> --- a/Documentation/hwmon/max6650.rst
> +++ b/Documentation/hwmon/max6650.rst
> @@ -55,7 +55,7 @@ Usage notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> Module parameters
> diff --git a/Documentation/hwmon/max8688.rst b/Documentation/hwmon/max8688.rst
> index 009487759c61..71e7f2cbe2e2 100644
> --- a/Documentation/hwmon/max8688.rst
> +++ b/Documentation/hwmon/max8688.rst
> @@ -28,7 +28,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/menf21bmc.rst b/Documentation/hwmon/menf21bmc.rst
> index 1f0c6b2235ab..978691d5956d 100644
> --- a/Documentation/hwmon/menf21bmc.rst
> +++ b/Documentation/hwmon/menf21bmc.rst
> @@ -28,7 +28,7 @@ Usage Notes
> This driver is part of the MFD driver named "menf21bmc" and does
> not auto-detect devices.
> You will have to instantiate the MFD driver explicitly.
> -Please see Documentation/i2c/instantiating-devices for
> +Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> Sysfs entries
> diff --git a/Documentation/hwmon/pcf8591.rst b/Documentation/hwmon/pcf8591.rst
> index e98bd542a441..5c4e85f53177 100644
> --- a/Documentation/hwmon/pcf8591.rst
> +++ b/Documentation/hwmon/pcf8591.rst
> @@ -68,7 +68,7 @@ Accessing PCF8591 via /sys interface
> The PCF8591 is plainly impossible to detect! Thus the driver won't even
> try. You have to explicitly instantiate the device at the relevant
> address (in the interval [0x48..0x4f]) either through platform data, or
> -using the sysfs interface. See Documentation/i2c/instantiating-devices
> +using the sysfs interface. See Documentation/i2c/instantiating-devices.rst
> for details.
>
> Directories are being created for each instantiated PCF8591:
> diff --git a/Documentation/hwmon/sht3x.rst b/Documentation/hwmon/sht3x.rst
> index 978a7117e4b2..95a850d5b2c1 100644
> --- a/Documentation/hwmon/sht3x.rst
> +++ b/Documentation/hwmon/sht3x.rst
> @@ -26,7 +26,7 @@ scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500.
>
> The device communicates with the I2C protocol. Sensors can have the I2C
> addresses 0x44 or 0x45, depending on the wiring. See
> -Documentation/i2c/instantiating-devices for methods to instantiate the device.
> +Documentation/i2c/instantiating-devices.rst for methods to instantiate the device.
>
> There are two options configurable by means of sht3x_platform_data:
>
> diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst
> index aa116332ba26..70c1192bbd8c 100644
> --- a/Documentation/hwmon/shtc1.rst
> +++ b/Documentation/hwmon/shtc1.rst
> @@ -36,7 +36,7 @@ humidity is expressed as a percentage. Driver can be used as well for SHTW1
> chip, which has the same electrical interface.
>
> The device communicates with the I2C protocol. All sensors are set to I2C
> -address 0x70. See Documentation/i2c/instantiating-devices for methods to
> +address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to
> instantiate the device.
>
> There are two options configurable by means of shtc1_platform_data:
> diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst
> index 15d25806d585..205de6148fcb 100644
> --- a/Documentation/hwmon/tmp103.rst
> +++ b/Documentation/hwmon/tmp103.rst
> @@ -30,4 +30,4 @@ The driver provides the common sysfs-interface for temperatures (see
> Documentation/hwmon/sysfs-interface.rst under Temperatures).
>
> Please refer how to instantiate this driver:
> -Documentation/i2c/instantiating-devices
> +Documentation/i2c/instantiating-devices.rst
> diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst
> index b691e30479dd..8fe3e1c3572e 100644
> --- a/Documentation/hwmon/tps40422.rst
> +++ b/Documentation/hwmon/tps40422.rst
> @@ -28,7 +28,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/ucd9000.rst b/Documentation/hwmon/ucd9000.rst
> index ebc4f2b3bfea..746f21fcb48c 100644
> --- a/Documentation/hwmon/ucd9000.rst
> +++ b/Documentation/hwmon/ucd9000.rst
> @@ -64,7 +64,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/ucd9200.rst b/Documentation/hwmon/ucd9200.rst
> index b819dfd75f71..4f0e7c3ca6f4 100644
> --- a/Documentation/hwmon/ucd9200.rst
> +++ b/Documentation/hwmon/ucd9200.rst
> @@ -40,7 +40,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/via686a.rst b/Documentation/hwmon/via686a.rst
> index a343c35df740..7ab9ddebcf79 100644
> --- a/Documentation/hwmon/via686a.rst
> +++ b/Documentation/hwmon/via686a.rst
> @@ -40,7 +40,7 @@ all as a 686A.
>
> The Via 686a southbridge has integrated hardware monitor functionality.
> It also has an I2C bus, but this driver only supports the hardware monitor.
> -For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro>
> +For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro.rst>
>
> The Via 686a implements three temperature sensors, two fan rotation speed
> sensors, five voltage sensors and alarms.
> diff --git a/Documentation/hwmon/zl6100.rst b/Documentation/hwmon/zl6100.rst
> index 41513bb7fe51..968aff10ce0a 100644
> --- a/Documentation/hwmon/zl6100.rst
> +++ b/Documentation/hwmon/zl6100.rst
> @@ -121,7 +121,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> .. warning::
> diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535.rst
> similarity index 82%
> rename from Documentation/i2c/busses/i2c-ali1535
> rename to Documentation/i2c/busses/i2c-ali1535.rst
> index 5d46342e486a..6941064730dc 100644
> --- a/Documentation/i2c/busses/i2c-ali1535
> +++ b/Documentation/i2c/busses/i2c-ali1535.rst
> @@ -1,16 +1,19 @@
> +=========================
> Kernel driver i2c-ali1535
> +=========================
>
> Supported adapters:
> * Acer Labs, Inc. ALI 1535 (south bridge)
> +
> Datasheet: Now under NDA
> http://www.ali.com.tw/
>
> Authors:
> - Frodo Looijaard <frodol@dds.nl>,
> - Philip Edelbrock <phil@netroedge.com>,
> - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> - Dan Eaton <dan.eaton@rocketlogix.com>,
> - Stephen Rousset<stephen.rousset@rocketlogix.com>
> + - Frodo Looijaard <frodol@dds.nl>,
> + - Philip Edelbrock <phil@netroedge.com>,
> + - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> + - Dan Eaton <dan.eaton@rocketlogix.com>,
> + - Stephen Rousset<stephen.rousset@rocketlogix.com>
>
> Description
> -----------
> diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563.rst
> similarity index 93%
> rename from Documentation/i2c/busses/i2c-ali1563
> rename to Documentation/i2c/busses/i2c-ali1563.rst
> index 41b1a077e4c7..eec32c3ba92a 100644
> --- a/Documentation/i2c/busses/i2c-ali1563
> +++ b/Documentation/i2c/busses/i2c-ali1563.rst
> @@ -1,7 +1,10 @@
> +=========================
> Kernel driver i2c-ali1563
> +=========================
>
> Supported adapters:
> * Acer Labs, Inc. ALI 1563 (south bridge)
> +
> Datasheet: Now under NDA
> http://www.ali.com.tw/
>
> diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3.rst
> similarity index 72%
> rename from Documentation/i2c/busses/i2c-ali15x3
> rename to Documentation/i2c/busses/i2c-ali15x3.rst
> index 42888d8ac124..c70f7c66db51 100644
> --- a/Documentation/i2c/busses/i2c-ali15x3
> +++ b/Documentation/i2c/busses/i2c-ali15x3.rst
> @@ -1,20 +1,23 @@
> +=========================
> Kernel driver i2c-ali15x3
> +=========================
>
> Supported adapters:
> * Acer Labs, Inc. ALI 1533 and 1543C (south bridge)
> +
> Datasheet: Now under NDA
> http://www.ali.com.tw/
>
> Authors:
> - Frodo Looijaard <frodol@dds.nl>,
> - Philip Edelbrock <phil@netroedge.com>,
> - Mark D. Studebaker <mdsxyz123@yahoo.com>
> + - Frodo Looijaard <frodol@dds.nl>,
> + - Philip Edelbrock <phil@netroedge.com>,
> + - Mark D. Studebaker <mdsxyz123@yahoo.com>
>
> Module Parameters
> -----------------
>
> * force_addr: int
> - Initialize the base address of the i2c controller
> + Initialize the base address of the i2c controller
>
>
> Notes
> @@ -25,7 +28,9 @@ the BIOS. Does not do a PCI force; the device must still be present in
> lspci. Don't use this unless the driver complains that the base address is
> not set.
>
> -Example: 'modprobe i2c-ali15x3 force_addr=0xe800'
> +Example::
> +
> + modprobe i2c-ali15x3 force_addr=0xe800
>
> SMBus periodically hangs on ASUS P5A motherboards and can only be cleared
> by a power cycle. Cause unknown (see Issues below).
> @@ -38,47 +43,53 @@ This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
> M1541 and M1543C South Bridges.
>
> The M1543C is a South bridge for desktop systems.
> +
> The M1541 is a South bridge for portable systems.
> +
> They are part of the following ALI chipsets:
>
> * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and
> - 100MHz CPU Front Side bus
> + 100MHz CPU Front Side bus
> * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz
> - CPU Front Side bus
> + CPU Front Side bus
> +
> Some Aladdin V motherboards:
> - Asus P5A
> - Atrend ATC-5220
> - BCM/GVC VP1541
> - Biostar M5ALA
> - Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't
> - enable the 7101 device! **)
> - Iwill XA100 Plus
> - Micronics C200
> - Microstar (MSI) MS-5169
> + - Asus P5A
> + - Atrend ATC-5220
> + - BCM/GVC VP1541
> + - Biostar M5ALA
> + - Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't
> + enable the 7101 device!)
> + - Iwill XA100 Plus
> + - Micronics C200
> + - Microstar (MSI) MS-5169
>
> * "Aladdin IV" includes the M1541 Socket 7 North bridge
> - with host bus up to 83.3 MHz.
> + with host bus up to 83.3 MHz.
>
> For an overview of these chips see http://www.acerlabs.com. At this time the
> full data sheets on the web site are password protected, however if you
> contact the ALI office in San Jose they may give you the password.
>
> The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An
> -output of lspci will show something similar to the following:
> +output of lspci will show something similar to the following::
>
> 00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03)
> 00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED
> 00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3)
> 00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1)
>
> -** IMPORTANT **
> -** If you have a M1533 or M1543C on the board and you get
> -** "ali15x3: Error: Can't detect ali15x3!"
> -** then run lspci.
> -** If you see the 1533 and 5229 devices but NOT the 7101 device,
> -** then you must enable ACPI, the PMU, SMB, or something similar
> -** in the BIOS.
> -** The driver won't work if it can't find the M7101 device.
> +.. important::
> +
> + If you have a M1533 or M1543C on the board and you get
> + "ali15x3: Error: Can't detect ali15x3!"
> + then run lspci.
> +
> + If you see the 1533 and 5229 devices but NOT the 7101 device,
> + then you must enable ACPI, the PMU, SMB, or something similar
> + in the BIOS.
> +
> + The driver won't work if it can't find the M7101 device.
>
> The SMB controller is part of the M7101 device, which is an ACPI-compliant
> Power Management Unit (PMU).
> diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2
> deleted file mode 100644
> index 6571487171f4..000000000000
> --- a/Documentation/i2c/busses/i2c-amd-mp2
> +++ /dev/null
> @@ -1,23 +0,0 @@
> -Kernel driver i2c-amd-mp2
> -
> -Supported adapters:
> - * AMD MP2 PCIe interface
> -
> -Datasheet: not publicly available.
> -
> -Authors:
> - Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
> - Nehal Shah <nehal-bakulchandra.shah@amd.com>
> - Elie Morisse <syniurge@gmail.com>
> -
> -Description
> ------------
> -
> -The MP2 is an ARM processor programmed as an I2C controller and communicating
> -with the x86 host through PCI.
> -
> -If you see something like this:
> -
> -03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
> -
> -in your 'lspci -v', then this driver is for your device.
> diff --git a/Documentation/i2c/busses/i2c-amd-mp2.rst b/Documentation/i2c/busses/i2c-amd-mp2.rst
> new file mode 100644
> index 000000000000..ebc2fa899325
> --- /dev/null
> +++ b/Documentation/i2c/busses/i2c-amd-mp2.rst
> @@ -0,0 +1,25 @@
> +=========================
> +Kernel driver i2c-amd-mp2
> +=========================
> +
> +Supported adapters:
> + * AMD MP2 PCIe interface
> +
> +Datasheet: not publicly available.
> +
> +Authors:
> + - Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
> + - Nehal Shah <nehal-bakulchandra.shah@amd.com>
> + - Elie Morisse <syniurge@gmail.com>
> +
> +Description
> +-----------
> +
> +The MP2 is an ARM processor programmed as an I2C controller and communicating
> +with the x86 host through PCI.
> +
> +If you see something like this::
> +
> + 03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
> +
> +in your ``lspci -v``, then this driver is for your device.
> diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756.rst
> similarity index 79%
> rename from Documentation/i2c/busses/i2c-amd756
> rename to Documentation/i2c/busses/i2c-amd756.rst
> index 67f30874d0bf..bc93f392a4fc 100644
> --- a/Documentation/i2c/busses/i2c-amd756
> +++ b/Documentation/i2c/busses/i2c-amd756.rst
> @@ -1,18 +1,22 @@
> +========================
> Kernel driver i2c-amd756
> +========================
>
> Supported adapters:
> * AMD 756
> * AMD 766
> * AMD 768
> * AMD 8111
> +
> Datasheets: Publicly available on AMD website
>
> * nVidia nForce
> +
> Datasheet: Unavailable
>
> Authors:
> - Frodo Looijaard <frodol@dds.nl>,
> - Philip Edelbrock <phil@netroedge.com>
> + - Frodo Looijaard <frodol@dds.nl>,
> + - Philip Edelbrock <phil@netroedge.com>
>
> Description
> -----------
> diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111.rst
> similarity index 66%
> rename from Documentation/i2c/busses/i2c-amd8111
> rename to Documentation/i2c/busses/i2c-amd8111.rst
> index 460dd6635fd2..d08bf0a7f0ac 100644
> --- a/Documentation/i2c/busses/i2c-amd8111
> +++ b/Documentation/i2c/busses/i2c-amd8111.rst
> @@ -1,4 +1,6 @@
> +=========================
> Kernel driver i2c-adm8111
> +=========================
>
> Supported adapters:
> * AMD-8111 SMBus 2.0 PCI interface
> @@ -13,14 +15,14 @@ Author: Vojtech Pavlik <vojtech@suse.cz>
> Description
> -----------
>
> -If you see something like this:
> +If you see something like this::
>
> -00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
> - Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
> - Flags: medium devsel, IRQ 19
> - I/O ports at d400 [size=32]
> + 00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
> + Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
> + Flags: medium devsel, IRQ 19
> + I/O ports at d400 [size=32]
>
> -in your 'lspci -v', then this driver is for your chipset.
> +in your ``lspci -v``, then this driver is for your chipset.
>
> Process Call Support
> --------------------
> diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c.rst
> similarity index 91%
> rename from Documentation/i2c/busses/i2c-diolan-u2c
> rename to Documentation/i2c/busses/i2c-diolan-u2c.rst
> index 0d6018c316c7..c18cbdcdf73c 100644
> --- a/Documentation/i2c/busses/i2c-diolan-u2c
> +++ b/Documentation/i2c/busses/i2c-diolan-u2c.rst
> @@ -1,7 +1,10 @@
> +============================
> Kernel driver i2c-diolan-u2c
> +============================
>
> Supported adapters:
> * Diolan U2C-12 I2C-USB adapter
> +
> Documentation:
> http://www.diolan.com/i2c/u2c12.html
>
> diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801.rst
> similarity index 89%
> rename from Documentation/i2c/busses/i2c-i801
> rename to Documentation/i2c/busses/i2c-i801.rst
> index d247edcb0f99..976b42a15129 100644
> --- a/Documentation/i2c/busses/i2c-i801
> +++ b/Documentation/i2c/busses/i2c-i801.rst
> @@ -1,4 +1,7 @@
> +======================
> Kernel driver i2c-i801
> +======================
> +
>
> Supported adapters:
> * Intel 82801AA and 82801AB (ICH and ICH0 - part of the
> @@ -38,27 +41,32 @@ Supported adapters:
> * Intel Ice Lake (PCH)
> * Intel Comet Lake (PCH)
> * Intel Elkhart Lake (PCH)
> +
> Datasheets: Publicly available at the Intel website
>
> On Intel Patsburg and later chipsets, both the normal host SMBus controller
> and the additional 'Integrated Device Function' controllers are supported.
>
> Authors:
> - Mark Studebaker <mdsxyz123@yahoo.com>
> - Jean Delvare <jdelvare@suse.de>
> + - Mark Studebaker <mdsxyz123@yahoo.com>
> + - Jean Delvare <jdelvare@suse.de>
>
>
> Module Parameters
> -----------------
>
> * disable_features (bit vector)
> +
> Disable selected features normally supported by the device. This makes it
> possible to work around possible driver or hardware bugs if the feature in
> question doesn't work as intended for whatever reason. Bit values:
> +
> + ==== =========================================
> 0x01 disable SMBus PEC
> 0x02 disable the block buffer
> 0x08 disable the I2C block read functionality
> 0x10 don't use interrupts
> + ==== =========================================
>
>
> Description
> @@ -71,7 +79,7 @@ Pentium-based PCs, '815E' chipset, and others.
>
> The ICH chips contain at least SEVEN separate PCI functions in TWO logical
> PCI devices. An output of lspci will show something similar to the
> -following:
> +following::
>
> 00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01)
> 00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01)
> @@ -138,14 +146,14 @@ and you think there's something interesting on the SMBus (e.g. a
> hardware monitoring chip), you need to add your board to the list.
>
> The motherboard is identified using the subvendor and subdevice IDs of the
> -host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0":
> +host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``::
>
> -00:00.0 Class 0600: 8086:2570 (rev 02)
> - Subsystem: 1043:80f2
> - Flags: bus master, fast devsel, latency 0
> - Memory at fc000000 (32-bit, prefetchable) [size=32M]
> - Capabilities: [e4] #09 [2106]
> - Capabilities: [a0] AGP version 3.0
> + 00:00.0 Class 0600: 8086:2570 (rev 02)
> + Subsystem: 1043:80f2
> + Flags: bus master, fast devsel, latency 0
> + Memory at fc000000 (32-bit, prefetchable) [size=32M]
> + Capabilities: [e4] #09 [2106]
> + Capabilities: [a0] AGP version 3.0
>
> Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043
> (Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic
> @@ -164,7 +172,8 @@ kernel. It's very convenient if you just want to check if there's
> anything interesting on your hidden ICH SMBus.
>
>
> -**********************
> +----------------------------------------------------------------------------
> +
> The lm_sensors project gratefully acknowledges the support of Texas
> Instruments in the initial development of this driver.
>
> diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt.rst
> similarity index 81%
> rename from Documentation/i2c/busses/i2c-ismt
> rename to Documentation/i2c/busses/i2c-ismt.rst
> index 737355822c0b..8e74919a3fdf 100644
> --- a/Documentation/i2c/busses/i2c-ismt
> +++ b/Documentation/i2c/busses/i2c-ismt.rst
> @@ -1,4 +1,7 @@
> +======================
> Kernel driver i2c-ismt
> +======================
> +
>
> Supported adapters:
> * Intel S12xx series SOCs
> @@ -11,16 +14,21 @@ Module Parameters
> -----------------
>
> * bus_speed (unsigned int)
> +
> Allows changing of the bus speed. Normally, the bus speed is set by the BIOS
> and never needs to be changed. However, some SMBus analyzers are too slow for
> monitoring the bus during debug, thus the need for this module parameter.
> Specify the bus speed in kHz.
> +
> Available bus frequency settings:
> - 0 no change
> - 80 kHz
> - 100 kHz
> - 400 kHz
> - 1000 kHz
> +
> + ==== =========
> + 0 no change
> + 80 kHz
> + 100 kHz
> + 400 kHz
> + 1000 kHz
> + ==== =========
>
>
> Description
> @@ -30,7 +38,7 @@ The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers
> targeted primarily at the microserver and storage markets.
>
> The S12xx series contain a pair of PCI functions. An output of lspci will show
> -something similar to the following:
> +something similar to the following::
>
> 00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0
> 00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1
> diff --git a/Documentation/i2c/busses/i2c-mlxcpld b/Documentation/i2c/busses/i2c-mlxcpld.rst
> similarity index 88%
> rename from Documentation/i2c/busses/i2c-mlxcpld
> rename to Documentation/i2c/busses/i2c-mlxcpld.rst
> index 925904aa9b57..9a0b2916aa71 100644
> --- a/Documentation/i2c/busses/i2c-mlxcpld
> +++ b/Documentation/i2c/busses/i2c-mlxcpld.rst
> @@ -1,9 +1,12 @@
> +==================
> Driver i2c-mlxcpld
> +==================
>
> Author: Michael Shych <michaelsh@mellanox.com>
>
> This is the Mellanox I2C controller logic, implemented in Lattice CPLD
> device.
> +
> Device supports:
> - Master mode.
> - One physical bus.
> @@ -20,6 +23,8 @@ The next transaction types are supported:
> - Write Byte/Block.
>
> Registers:
> +
> +=============== === =======================================================================
> CPBLTY 0x0 - capability reg.
> Bits [6:5] - transaction length. b01 - 72B is supported,
> 36B in other case.
> @@ -49,3 +54,4 @@ DATAx 0xa - 0x54 - 68 bytes data buffer regs.
> For read transactions address is sent in a separate transaction and
> specified in the four first bytes (DATA0 - DATA3). Data is read
> starting from DATA0.
> +=============== === =======================================================================
> diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2.rst
> similarity index 68%
> rename from Documentation/i2c/busses/i2c-nforce2
> rename to Documentation/i2c/busses/i2c-nforce2.rst
> index 9698c396b830..f5c57ea31cd3 100644
> --- a/Documentation/i2c/busses/i2c-nforce2
> +++ b/Documentation/i2c/busses/i2c-nforce2.rst
> @@ -1,4 +1,6 @@
> +=========================
> Kernel driver i2c-nforce2
> +=========================
>
> Supported adapters:
> * nForce2 MCP 10de:0064
> @@ -16,26 +18,27 @@ Supported adapters:
> * nForce MCP78S 10de:0752
> * nForce MCP79 10de:0AA2
>
> -Datasheet: not publicly available, but seems to be similar to the
> +Datasheet:
> + not publicly available, but seems to be similar to the
> AMD-8111 SMBus 2.0 adapter.
>
> Authors:
> - Hans-Frieder Vogt <hfvogt@gmx.net>,
> - Thomas Leibold <thomas@plx.com>,
> - Patrick Dreker <patrick@dreker.de>
> + - Hans-Frieder Vogt <hfvogt@gmx.net>,
> + - Thomas Leibold <thomas@plx.com>,
> + - Patrick Dreker <patrick@dreker.de>
>
> Description
> -----------
>
> i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP.
>
> -If your 'lspci -v' listing shows something like the following,
> +If your ``lspci -v`` listing shows something like the following::
>
> -00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
> - Subsystem: Asustek Computer, Inc.: Unknown device 0c11
> - Flags: 66Mhz, fast devsel, IRQ 5
> - I/O ports at c000 [size=32]
> - Capabilities: <available only to root>
> + 00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
> + Subsystem: Asustek Computer, Inc.: Unknown device 0c11
> + Flags: 66Mhz, fast devsel, IRQ 5
> + I/O ports at c000 [size=32]
> + Capabilities: <available only to root>
>
> then this driver should support the SMBuses of your motherboard.
>
> diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
> similarity index 63%
> rename from Documentation/i2c/busses/i2c-nvidia-gpu
> rename to Documentation/i2c/busses/i2c-nvidia-gpu.rst
> index 31884d2b2eb5..38fb8a4c8756 100644
> --- a/Documentation/i2c/busses/i2c-nvidia-gpu
> +++ b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
> @@ -1,4 +1,6 @@
> +============================
> Kernel driver i2c-nvidia-gpu
> +============================
>
> Datasheet: not publicly available.
>
> @@ -11,8 +13,8 @@ Description
> i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing
> and later GPUs and it is used to communicate with Type-C controller on GPUs.
>
> -If your 'lspci -v' listing shows something like the following,
> +If your ``lspci -v`` listing shows something like the following::
>
> -01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
> + 01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
>
> then this driver should support the I2C controller of your GPU.
> diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores.rst
> similarity index 82%
> rename from Documentation/i2c/busses/i2c-ocores
> rename to Documentation/i2c/busses/i2c-ocores.rst
> index 9caaf7df1b2f..f5e175f2a2a6 100644
> --- a/Documentation/i2c/busses/i2c-ocores
> +++ b/Documentation/i2c/busses/i2c-ocores.rst
> @@ -1,4 +1,6 @@
> +========================
> Kernel driver i2c-ocores
> +========================
>
> Supported adapters:
> * OpenCores.org I2C controller by Richard Herveille (see datasheet link)
> @@ -23,9 +25,9 @@ distance between registers and the input clock speed.
> There is also a possibility to attach a list of i2c_board_info which
> the i2c-ocores driver will add to the bus upon creation.
>
> -E.G. something like:
> +E.G. something like::
>
> -static struct resource ocores_resources[] = {
> + static struct resource ocores_resources[] = {
> [0] = {
> .start = MYI2C_BASEADDR,
> .end = MYI2C_BASEADDR + 8,
> @@ -36,10 +38,10 @@ static struct resource ocores_resources[] = {
> .end = MYI2C_IRQ,
> .flags = IORESOURCE_IRQ,
> },
> -};
> + };
>
> -/* optional board info */
> -struct i2c_board_info ocores_i2c_board_info[] = {
> + /* optional board info */
> + struct i2c_board_info ocores_i2c_board_info[] = {
> {
> I2C_BOARD_INFO("tsc2003", 0x48),
> .platform_data = &tsc2003_platform_data,
> @@ -49,20 +51,20 @@ struct i2c_board_info ocores_i2c_board_info[] = {
> I2C_BOARD_INFO("adv7180", 0x42 >> 1),
> .irq = ADV_IRQ
> }
> -};
> + };
>
> -static struct ocores_i2c_platform_data myi2c_data = {
> + static struct ocores_i2c_platform_data myi2c_data = {
> .regstep = 2, /* two bytes between registers */
> .clock_khz = 50000, /* input clock of 50MHz */
> .devices = ocores_i2c_board_info, /* optional table of devices */
> .num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */
> -};
> + };
>
> -static struct platform_device myi2c = {
> + static struct platform_device myi2c = {
> .name = "ocores-i2c",
> .dev = {
> .platform_data = &myi2c_data,
> },
> .num_resources = ARRAY_SIZE(ocores_resources),
> .resource = ocores_resources,
> -};
> + };
> diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport
> deleted file mode 100644
> index c3dbb3bfd814..000000000000
> --- a/Documentation/i2c/busses/i2c-parport
> +++ /dev/null
> @@ -1,178 +0,0 @@
> -Kernel driver i2c-parport
> -
> -Author: Jean Delvare <jdelvare@suse.de>
> -
> -This is a unified driver for several i2c-over-parallel-port adapters,
> -such as the ones made by Philips, Velleman or ELV. This driver is
> -meant as a replacement for the older, individual drivers:
> - * i2c-philips-par
> - * i2c-elv
> - * i2c-velleman
> - * video/i2c-parport (NOT the same as this one, dedicated to home brew
> - teletext adapters)
> -
> -It currently supports the following devices:
> - * (type=0) Philips adapter
> - * (type=1) home brew teletext adapter
> - * (type=2) Velleman K8000 adapter
> - * (type=3) ELV adapter
> - * (type=4) Analog Devices ADM1032 evaluation board
> - * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
> - * (type=6) Barco LPT->DVI (K5800236) adapter
> - * (type=7) One For All JP1 parallel port adapter
> - * (type=8) VCT-jig
> -
> -These devices use different pinout configurations, so you have to tell
> -the driver what you have, using the type module parameter. There is no
> -way to autodetect the devices. Support for different pinout configurations
> -can be easily added when needed.
> -
> -Earlier kernels defaulted to type=0 (Philips). But now, if the type
> -parameter is missing, the driver will simply fail to initialize.
> -
> -SMBus alert support is available on adapters which have this line properly
> -connected to the parallel port's interrupt pin.
> -
> -
> -Building your own adapter
> --------------------------
> -
> -If you want to build you own i2c-over-parallel-port adapter, here is
> -a sample electronics schema (credits go to Sylvain Munaut):
> -
> -Device PC
> -Side ___________________Vdd (+) Side
> - | | |
> - --- --- ---
> - | | | | | |
> - |R| |R| |R|
> - | | | | | |
> - --- --- ---
> - | | |
> - | | /| |
> -SCL ----------x--------o |-----------x------------------- pin 2
> - | \| | |
> - | | |
> - | |\ | |
> -SDA ----------x----x---| o---x--------------------------- pin 13
> - | |/ |
> - | |
> - | /| |
> - ---------o |----------------x-------------- pin 3
> - \| | |
> - | |
> - --- ---
> - | | | |
> - |R| |R|
> - | | | |
> - --- ---
> - | |
> - ### ###
> - GND GND
> -
> -Remarks:
> - - This is the exact pinout and electronics used on the Analog Devices
> - evaluation boards.
> - /|
> - - All inverters -o |- must be 74HC05, they must be open collector output.
> - \|
> - - All resitors are 10k.
> - - Pins 18-25 of the parallel port connected to GND.
> - - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
> - The ADM1032 evaluation board uses D4-D7. Beware that the amount of
> - current you can draw from the parallel port is limited. Also note that
> - all connected lines MUST BE driven at the same state, else you'll short
> - circuit the output buffers! So plugging the I2C adapter after loading
> - the i2c-parport module might be a good safety since data line state
> - prior to init may be unknown.
> - - This is 5V!
> - - Obviously you cannot read SCL (so it's not really standard-compliant).
> - Pretty easy to add, just copy the SDA part and use another input pin.
> - That would give (ELV compatible pinout):
> -
> -
> -Device PC
> -Side ______________________________Vdd (+) Side
> - | | | |
> - --- --- --- ---
> - | | | | | | | |
> - |R| |R| |R| |R|
> - | | | | | | | |
> - --- --- --- ---
> - | | | |
> - | | |\ | |
> -SCL ----------x--------x--| o---x------------------------ pin 15
> - | | |/ |
> - | | |
> - | | /| |
> - | ---o |-------------x-------------- pin 2
> - | \| | |
> - | | |
> - | | |
> - | |\ | |
> -SDA ---------------x---x--| o--------x------------------- pin 10
> - | |/ |
> - | |
> - | /| |
> - ---o |------------------x--------- pin 3
> - \| | |
> - | |
> - --- ---
> - | | | |
> - |R| |R|
> - | | | |
> - --- ---
> - | |
> - ### ###
> - GND GND
> -
> -
> -If possible, you should use the same pinout configuration as existing
> -adapters do, so you won't even have to change the code.
> -
> -
> -Similar (but different) drivers
> --------------------------------
> -
> -This driver is NOT the same as the i2c-pport driver found in the i2c
> -package. The i2c-pport driver makes use of modern parallel port features so
> -that you don't need additional electronics. It has other restrictions
> -however, and was not ported to Linux 2.6 (yet).
> -
> -This driver is also NOT the same as the i2c-pcf-epp driver found in the
> -lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as
> -an I2C bus directly. Instead, it uses it to control an external I2C bus
> -master. That driver was not ported to Linux 2.6 (yet) either.
> -
> -
> -Legacy documentation for Velleman adapter
> ------------------------------------------
> -
> -Useful links:
> -Velleman http://www.velleman.be/
> -Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html
> -
> -The project has lead to new libs for the Velleman K8000 and K8005:
> - LIBK8000 v1.99.1 and LIBK8005 v0.21
> -With these libs, you can control the K8000 interface card and the K8005
> -stepper motor card with the simple commands which are in the original
> -Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
> -many more, using /dev/velleman.
> - http://home.wanadoo.nl/hihihi/libk8000.htm
> - http://home.wanadoo.nl/hihihi/libk8005.htm
> - http://struyve.mine.nu:8080/index.php?block=k8000
> - http://sourceforge.net/projects/libk8005/
> -
> -
> -One For All JP1 parallel port adapter
> --------------------------------------
> -
> -The JP1 project revolves around a set of remote controls which expose
> -the I2C bus their internal configuration EEPROM lives on via a 6 pin
> -jumper in the battery compartment. More details can be found at:
> -
> -http://www.hifi-remote.com/jp1/
> -
> -Details of the simple parallel port hardware can be found at:
> -
> -http://www.hifi-remote.com/jp1/hardware.shtml
> diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light.rst
> similarity index 92%
> rename from Documentation/i2c/busses/i2c-parport-light
> rename to Documentation/i2c/busses/i2c-parport-light.rst
> index 7071b8ba0af4..af85c8dfcd1a 100644
> --- a/Documentation/i2c/busses/i2c-parport-light
> +++ b/Documentation/i2c/busses/i2c-parport-light.rst
> @@ -1,4 +1,6 @@
> +===============================
> Kernel driver i2c-parport-light
> +===============================
>
> Author: Jean Delvare <jdelvare@suse.de>
>
> diff --git a/Documentation/i2c/busses/i2c-parport.rst b/Documentation/i2c/busses/i2c-parport.rst
> new file mode 100644
> index 000000000000..fae7c7ba9bd1
> --- /dev/null
> +++ b/Documentation/i2c/busses/i2c-parport.rst
> @@ -0,0 +1,190 @@
> +=========================
> +Kernel driver i2c-parport
> +=========================
> +
> +Author: Jean Delvare <jdelvare@suse.de>
> +
> +This is a unified driver for several i2c-over-parallel-port adapters,
> +such as the ones made by Philips, Velleman or ELV. This driver is
> +meant as a replacement for the older, individual drivers:
> +
> + * i2c-philips-par
> + * i2c-elv
> + * i2c-velleman
> + * video/i2c-parport
> + (NOT the same as this one, dedicated to home brew teletext adapters)
> +
> +It currently supports the following devices:
> +
> + * (type=0) Philips adapter
> + * (type=1) home brew teletext adapter
> + * (type=2) Velleman K8000 adapter
> + * (type=3) ELV adapter
> + * (type=4) Analog Devices ADM1032 evaluation board
> + * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
> + * (type=6) Barco LPT->DVI (K5800236) adapter
> + * (type=7) One For All JP1 parallel port adapter
> + * (type=8) VCT-jig
> +
> +These devices use different pinout configurations, so you have to tell
> +the driver what you have, using the type module parameter. There is no
> +way to autodetect the devices. Support for different pinout configurations
> +can be easily added when needed.
> +
> +Earlier kernels defaulted to type=0 (Philips). But now, if the type
> +parameter is missing, the driver will simply fail to initialize.
> +
> +SMBus alert support is available on adapters which have this line properly
> +connected to the parallel port's interrupt pin.
> +
> +
> +Building your own adapter
> +-------------------------
> +
> +If you want to build you own i2c-over-parallel-port adapter, here is
> +a sample electronics schema (credits go to Sylvain Munaut)::
> +
> + Device PC
> + Side ___________________Vdd (+) Side
> + | | |
> + --- --- ---
> + | | | | | |
> + |R| |R| |R|
> + | | | | | |
> + --- --- ---
> + | | |
> + | | /| |
> + SCL ----------x--------o |-----------x------------------- pin 2
> + | \| | |
> + | | |
> + | |\ | |
> + SDA ----------x----x---| o---x--------------------------- pin 13
> + | |/ |
> + | |
> + | /| |
> + ---------o |----------------x-------------- pin 3
> + \| | |
> + | |
> + --- ---
> + | | | |
> + |R| |R|
> + | | | |
> + --- ---
> + | |
> + ### ###
> + GND GND
> +
> +Remarks:
> + - This is the exact pinout and electronics used on the Analog Devices
> + evaluation boards.
> + - All inverters::
> +
> + /|
> + -o |-
> + \|
> +
> + must be 74HC05, they must be open collector output.
> + - All resitors are 10k.
> + - Pins 18-25 of the parallel port connected to GND.
> + - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
> + The ADM1032 evaluation board uses D4-D7. Beware that the amount of
> + current you can draw from the parallel port is limited. Also note that
> + all connected lines MUST BE driven at the same state, else you'll short
> + circuit the output buffers! So plugging the I2C adapter after loading
> + the i2c-parport module might be a good safety since data line state
> + prior to init may be unknown.
> + - This is 5V!
> + - Obviously you cannot read SCL (so it's not really standard-compliant).
> + Pretty easy to add, just copy the SDA part and use another input pin.
> + That would give (ELV compatible pinout)::
> +
> +
> + Device PC
> + Side ______________________________Vdd (+) Side
> + | | | |
> + --- --- --- ---
> + | | | | | | | |
> + |R| |R| |R| |R|
> + | | | | | | | |
> + --- --- --- ---
> + | | | |
> + | | |\ | |
> + SCL ----------x--------x--| o---x------------------------ pin 15
> + | | |/ |
> + | | |
> + | | /| |
> + | ---o |-------------x-------------- pin 2
> + | \| | |
> + | | |
> + | | |
> + | |\ | |
> + SDA ---------------x---x--| o--------x------------------- pin 10
> + | |/ |
> + | |
> + | /| |
> + ---o |------------------x--------- pin 3
> + \| | |
> + | |
> + --- ---
> + | | | |
> + |R| |R|
> + | | | |
> + --- ---
> + | |
> + ### ###
> + GND GND
> +
> +
> +If possible, you should use the same pinout configuration as existing
> +adapters do, so you won't even have to change the code.
> +
> +
> +Similar (but different) drivers
> +-------------------------------
> +
> +This driver is NOT the same as the i2c-pport driver found in the i2c
> +package. The i2c-pport driver makes use of modern parallel port features so
> +that you don't need additional electronics. It has other restrictions
> +however, and was not ported to Linux 2.6 (yet).
> +
> +This driver is also NOT the same as the i2c-pcf-epp driver found in the
> +lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as
> +an I2C bus directly. Instead, it uses it to control an external I2C bus
> +master. That driver was not ported to Linux 2.6 (yet) either.
> +
> +
> +Legacy documentation for Velleman adapter
> +-----------------------------------------
> +
> +Useful links:
> +
> +- Velleman http://www.velleman.be/
> +- Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html
> +
> +The project has lead to new libs for the Velleman K8000 and K8005:
> +
> + LIBK8000 v1.99.1 and LIBK8005 v0.21
> +
> +With these libs, you can control the K8000 interface card and the K8005
> +stepper motor card with the simple commands which are in the original
> +Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
> +many more, using /dev/velleman.
> +
> + - http://home.wanadoo.nl/hihihi/libk8000.htm
> + - http://home.wanadoo.nl/hihihi/libk8005.htm
> + - http://struyve.mine.nu:8080/index.php?block=k8000
> + - http://sourceforge.net/projects/libk8005/
> +
> +
> +One For All JP1 parallel port adapter
> +-------------------------------------
> +
> +The JP1 project revolves around a set of remote controls which expose
> +the I2C bus their internal configuration EEPROM lives on via a 6 pin
> +jumper in the battery compartment. More details can be found at:
> +
> +http://www.hifi-remote.com/jp1/
> +
> +Details of the simple parallel port hardware can be found at:
> +
> +http://www.hifi-remote.com/jp1/hardware.shtml
> diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa.rst
> similarity index 72%
> rename from Documentation/i2c/busses/i2c-pca-isa
> rename to Documentation/i2c/busses/i2c-pca-isa.rst
> index b044e5265488..a254010c8055 100644
> --- a/Documentation/i2c/busses/i2c-pca-isa
> +++ b/Documentation/i2c/busses/i2c-pca-isa.rst
> @@ -1,6 +1,9 @@
> +=========================
> Kernel driver i2c-pca-isa
> +=========================
>
> Supported adapters:
> +
> This driver supports ISA boards using the Philips PCA 9564
> Parallel bus to I2C bus controller
>
> @@ -10,11 +13,11 @@ Module Parameters
> -----------------
>
> * base int
> - I/O base address
> + I/O base address
> * irq int
> - IRQ interrupt
> + IRQ interrupt
> * clock int
> - Clock rate as described in table 1 of PCA9564 datasheet
> + Clock rate as described in table 1 of PCA9564 datasheet
>
> Description
> -----------
> diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4.rst
> similarity index 92%
> rename from Documentation/i2c/busses/i2c-piix4
> rename to Documentation/i2c/busses/i2c-piix4.rst
> index 2703bc3acad0..5d4744842b41 100644
> --- a/Documentation/i2c/busses/i2c-piix4
> +++ b/Documentation/i2c/busses/i2c-piix4.rst
> @@ -1,4 +1,6 @@
> +=======================
> Kernel driver i2c-piix4
> +=======================
>
> Supported adapters:
> * Intel 82371AB PIIX4 and PIIX4E
> @@ -21,8 +23,8 @@ Supported adapters:
> Datasheet: Publicly available at the SMSC website http://www.smsc.com
>
> Authors:
> - Frodo Looijaard <frodol@dds.nl>
> - Philip Edelbrock <phil@netroedge.com>
> + - Frodo Looijaard <frodol@dds.nl>
> + - Philip Edelbrock <phil@netroedge.com>
>
>
> Module Parameters
> @@ -45,10 +47,10 @@ natively understands SMBus commands and you do not have to worry about
> timing problems. The bad news is that non-SMBus devices connected to it can
> confuse it mightily. Yes, this is known to happen...
>
> -Do 'lspci -v' and see whether it contains an entry like this:
> +Do ``lspci -v`` and see whether it contains an entry like this::
>
> -0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
> - Flags: medium devsel, IRQ 9
> + 0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
> + Flags: medium devsel, IRQ 9
>
> Bus and device numbers may differ, but the function number must be
> identical (like many PCI devices, the PIIX4 incorporates a number of
> @@ -91,7 +93,7 @@ the SMI mode.
> device is located at 00:0f.0.
> 2) Now you just need to change the value in 0xD2 register. Get it first with
> command: lspci -xxx -s 00:0f.0
> - If the value is 0x3 then you need to change it to 0x1
> + If the value is 0x3 then you need to change it to 0x1:
> setpci -s 00:0f.0 d2.b=1
>
> Please note that you don't need to do that in all cases, just when the SMBus is
> diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595.rst
> similarity index 74%
> rename from Documentation/i2c/busses/i2c-sis5595
> rename to Documentation/i2c/busses/i2c-sis5595.rst
> index ecd21fb49a8f..5614afe35e79 100644
> --- a/Documentation/i2c/busses/i2c-sis5595
> +++ b/Documentation/i2c/busses/i2c-sis5595.rst
> @@ -1,9 +1,11 @@
> +=========================
> Kernel driver i2c-sis5595
> +=========================
>
> Authors:
> - Frodo Looijaard <frodol@dds.nl>,
> - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> - Philip Edelbrock <phil@netroedge.com>
> + - Frodo Looijaard <frodol@dds.nl>,
> + - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> + - Philip Edelbrock <phil@netroedge.com>
>
> Supported adapters:
> * Silicon Integrated Systems Corp. SiS5595 Southbridge
> @@ -11,14 +13,19 @@ Supported adapters:
>
> Note: all have mfr. ID 0x1039.
>
> + ========= ======
> SUPPORTED PCI ID
> + ========= ======
> 5595 0008
> + ========= ======
>
> Note: these chips contain a 0008 device which is incompatible with the
> 5595. We recognize these by the presence of the listed
> "blacklist" PCI ID and refuse to load.
>
> + ============= ====== ================
> NOT SUPPORTED PCI ID BLACKLIST PCI ID
> + ============= ====== ================
> 540 0008 0540
> 550 0008 0550
> 5513 0008 5511
> @@ -36,15 +43,18 @@ Note: all have mfr. ID 0x1039.
> 735 0008 0735
> 745 0008 0745
> 746 0008 0746
> + ============= ====== ================
>
> Module Parameters
> -----------------
>
> -* force_addr=0xaddr Set the I/O base address. Useful for boards
> +================== =====================================================
> +force_addr=0xaddr Set the I/O base address. Useful for boards
> that don't set the address in the BIOS. Does not do a
> PCI force; the device must still be present in lspci.
> Don't use this unless the driver complains that the
> base address is not set.
> +================== =====================================================
>
> Description
> -----------
> diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630
> deleted file mode 100644
> index ee7943631074..000000000000
> --- a/Documentation/i2c/busses/i2c-sis630
> +++ /dev/null
> @@ -1,58 +0,0 @@
> -Kernel driver i2c-sis630
> -
> -Supported adapters:
> - * Silicon Integrated Systems Corp (SiS)
> - 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux)
> - 730 chipset
> - 964 chipset
> - * Possible other SiS chipsets ?
> -
> -Author: Alexander Malysh <amalysh@web.de>
> - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
> -
> -Module Parameters
> ------------------
> -
> -* force = [1|0] Forcibly enable the SIS630. DANGEROUS!
> - This can be interesting for chipsets not named
> - above to check if it works for you chipset, but DANGEROUS!
> -
> -* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
> - what your BIOS use). DANGEROUS! This should be a bit
> - faster, but freeze some systems (i.e. my Laptop).
> - SIS630/730 chip only.
> -
> -
> -Description
> ------------
> -
> -This SMBus only driver is known to work on motherboards with the above
> -named chipsets.
> -
> -If you see something like this:
> -
> -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
> -00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> -
> -or like this:
> -
> -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
> -00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> -
> -or like this:
> -
> -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
> -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
> - LPC Controller (rev 36)
> -
> -in your 'lspci' output , then this driver is for your chipset.
> -
> -Thank You
> ----------
> -Philip Edelbrock <phil@netroedge.com>
> -- testing SiS730 support
> -Mark M. Hoffman <mhoffman@lightlink.com>
> -- bug fixes
> -
> -To anyone else which I forgot here ;), thanks!
> -
> diff --git a/Documentation/i2c/busses/i2c-sis630.rst b/Documentation/i2c/busses/i2c-sis630.rst
> new file mode 100644
> index 000000000000..f37700e885f2
> --- /dev/null
> +++ b/Documentation/i2c/busses/i2c-sis630.rst
> @@ -0,0 +1,64 @@
> +========================
> +Kernel driver i2c-sis630
> +========================
> +
> +Supported adapters:
> + * Silicon Integrated Systems Corp (SiS)
> + 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux)
> + 730 chipset
> + 964 chipset
> + * Possible other SiS chipsets ?
> +
> +Author:
> + - Alexander Malysh <amalysh@web.de>
> + - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
> +
> +Module Parameters
> +-----------------
> +
> +================== =====================================================
> +force = [1|0] Forcibly enable the SIS630. DANGEROUS!
> + This can be interesting for chipsets not named
> + above to check if it works for you chipset,
> + but DANGEROUS!
> +
> +high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
> + what your BIOS use). DANGEROUS! This should be a bit
> + faster, but freeze some systems (i.e. my Laptop).
> + SIS630/730 chip only.
> +================== =====================================================
> +
> +
> +Description
> +-----------
> +
> +This SMBus only driver is known to work on motherboards with the above
> +named chipsets.
> +
> +If you see something like this::
> +
> + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
> + 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> +
> +or like this::
> +
> + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
> + 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> +
> +or like this::
> +
> + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
> + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
> + LPC Controller (rev 36)
> +
> +in your ``lspci`` output , then this driver is for your chipset.
> +
> +Thank You
> +---------
> +Philip Edelbrock <phil@netroedge.com>
> +- testing SiS730 support
> +Mark M. Hoffman <mhoffman@lightlink.com>
> +- bug fixes
> +
> +To anyone else which I forgot here ;), thanks!
> +
> diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x.rst
> similarity index 75%
> rename from Documentation/i2c/busses/i2c-sis96x
> rename to Documentation/i2c/busses/i2c-sis96x.rst
> index 0b979f3252a4..b84581ade213 100644
> --- a/Documentation/i2c/busses/i2c-sis96x
> +++ b/Documentation/i2c/busses/i2c-sis96x.rst
> @@ -1,11 +1,16 @@
> +========================
> Kernel driver i2c-sis96x
> +========================
>
> Replaces 2.4.x i2c-sis645
>
> Supported adapters:
> +
> * Silicon Integrated Systems Corp (SiS)
> +
> Any combination of these host bridges:
> 645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746
> +
> and these south bridges:
> 961, 962, 963(L)
>
> @@ -21,17 +26,17 @@ those of the SiS630, although they are located in a completely different
> place. Thanks to Alexander Malysh <amalysh@web.de> for providing the
> SiS630 datasheet (and driver).
>
> -The command "lspci" as root should produce something like these lines:
> +The command ``lspci`` as root should produce something like these lines::
>
> -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
> -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> -00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
> + 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
> + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> + 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
>
> -or perhaps this...
> +or perhaps this::
>
> -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
> -00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
> -00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
> + 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
> + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
> + 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
>
> (kernel versions later than 2.4.18 may fill in the "Unknown"s)
>
> @@ -50,7 +55,7 @@ TO DOs
> ------
>
> * The driver does not support SMBus block reads/writes; I may add them if a
> -scenario is found where they're needed.
> + scenario is found where they're needed.
>
>
> Thank You
> @@ -58,14 +63,19 @@ Thank You
>
> Mark D. Studebaker <mdsxyz123@yahoo.com>
> - design hints and bug fixes
> +
> Alexander Maylsh <amalysh@web.de>
> - ditto, plus an important datasheet... almost the one I really wanted
> +
> Hans-Günter Lütke Uphues <hg_lu@t-online.de>
> - patch for SiS735
> +
> Robert Zwerus <arzie@dds.nl>
> - testing for SiS645DX
> +
> Kianusch Sayah Karadji <kianusch@sk-tech.net>
> - patch for SiS645DX/962
> +
> Ken Healy
> - patch for SiS655
>
> diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm.rst
> similarity index 91%
> rename from Documentation/i2c/busses/i2c-taos-evm
> rename to Documentation/i2c/busses/i2c-taos-evm.rst
> index 60299555dcf0..f342e313ee3d 100644
> --- a/Documentation/i2c/busses/i2c-taos-evm
> +++ b/Documentation/i2c/busses/i2c-taos-evm.rst
> @@ -1,4 +1,6 @@
> +==========================
> Kernel driver i2c-taos-evm
> +==========================
>
> Author: Jean Delvare <jdelvare@suse.de>
>
> @@ -23,10 +25,10 @@ Using this driver
> In order to use this driver, you'll need the serport driver, and the
> inputattach tool, which is part of the input-utils package. The following
> commands will tell the kernel that you have a TAOS EVM on the first
> -serial port:
> +serial port::
>
> -# modprobe serport
> -# inputattach --taos-evm /dev/ttyS0
> + # modprobe serport
> + # inputattach --taos-evm /dev/ttyS0
>
>
> Technical details
> diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via.rst
> similarity index 61%
> rename from Documentation/i2c/busses/i2c-via
> rename to Documentation/i2c/busses/i2c-via.rst
> index 343870661ac3..df1df5adff7b 100644
> --- a/Documentation/i2c/busses/i2c-via
> +++ b/Documentation/i2c/busses/i2c-via.rst
> @@ -1,4 +1,6 @@
> +=====================
> Kernel driver i2c-via
> +=====================
>
> Supported adapters:
> * VIA Technologies, InC. VT82C586B
> @@ -15,20 +17,24 @@ The following VIA pci chipsets are supported:
> - MVP3, VP3, VP2/97, VPX/97
> - others with South bridge VT82C586B
>
> -Your lspci listing must show this :
> +Your ``lspci`` listing must show this ::
>
> Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10)
>
> - Problems?
> +Problems?
> +---------
>
> - Q: You have VT82C586B on the motherboard, but not in the listing.
> + Q:
> + You have VT82C586B on the motherboard, but not in the listing.
>
> - A: Go to your BIOS setup, section PCI devices or similar.
> + A:
> + Go to your BIOS setup, section PCI devices or similar.
> Turn USB support on, and try again.
>
> - Q: No error messages, but still i2c doesn't seem to work.
> + Q:
> + No error messages, but still i2c doesn't seem to work.
>
> - A: This can happen. This driver uses the pins VIA recommends in their
> + A:
> + This can happen. This driver uses the pins VIA recommends in their
> datasheets, but there are several ways the motherboard manufacturer
> can actually wire the lines.
> -
> diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro.rst
> similarity index 87%
> rename from Documentation/i2c/busses/i2c-viapro
> rename to Documentation/i2c/busses/i2c-viapro.rst
> index ab64ce21c254..1762f0cf93d0 100644
> --- a/Documentation/i2c/busses/i2c-viapro
> +++ b/Documentation/i2c/busses/i2c-viapro.rst
> @@ -1,4 +1,6 @@
> +========================
> Kernel driver i2c-viapro
> +========================
>
> Supported adapters:
> * VIA Technologies, Inc. VT82C596A/B
> @@ -26,9 +28,9 @@ Supported adapters:
> Datasheet: available on http://linux.via.com.tw
>
> Authors:
> - Kyösti Mälkki <kmalkki@cc.hut.fi>,
> - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> - Jean Delvare <jdelvare@suse.de>
> + - Kyösti Mälkki <kmalkki@cc.hut.fi>,
> + - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> + - Jean Delvare <jdelvare@suse.de>
>
> Module Parameters
> -----------------
> @@ -44,8 +46,9 @@ Description
> i2c-viapro is a true SMBus host driver for motherboards with one of the
> supported VIA south bridges.
>
> -Your lspci -n listing must show one of these :
> +Your ``lspci -n`` listing must show one of these :
>
> + ================ ======================
> device 1106:3050 (VT82C596A function 3)
> device 1106:3051 (VT82C596B function 3)
> device 1106:3057 (VT82C686 function 4)
> @@ -61,6 +64,7 @@ Your lspci -n listing must show one of these :
> device 1106:8353 (VX800/VX820)
> device 1106:8409 (VX855/VX875)
> device 1106:8410 (VX900)
> + ================ ======================
>
> If none of these show up, you should look in the BIOS for settings like
> enable ACPI / SMBus or even USB.
> diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst
> new file mode 100644
> index 000000000000..97ca4d510816
> --- /dev/null
> +++ b/Documentation/i2c/busses/index.rst
> @@ -0,0 +1,33 @@
> +. SPDX-License-Identifier: GPL-2.0
> +
> +===============
> +I2C Bus Drivers
> +===============
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + i2c-ali1535
> + i2c-ali1563
> + i2c-ali15x3
> + i2c-amd756
> + i2c-amd8111
> + i2c-amd-mp2
> + i2c-diolan-u2c
> + i2c-i801
> + i2c-ismt
> + i2c-mlxcpld
> + i2c-nforce2
> + i2c-nvidia-gpu
> + i2c-ocores
> + i2c-parport-light
> + i2c-parport
> + i2c-pca-isa
> + i2c-piix4
> + i2c-sis5595
> + i2c-sis630
> + i2c-sis96x
> + i2c-taos-evm
> + i2c-viapro
> + i2c-via
> + scx200_acb
> diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb.rst
> similarity index 86%
> rename from Documentation/i2c/busses/scx200_acb
> rename to Documentation/i2c/busses/scx200_acb.rst
> index ce83c871fe95..8dc7c352508c 100644
> --- a/Documentation/i2c/busses/scx200_acb
> +++ b/Documentation/i2c/busses/scx200_acb.rst
> @@ -1,4 +1,6 @@
> +========================
> Kernel driver scx200_acb
> +========================
>
> Author: Christer Weinigel <wingel@nano-system.com>
>
> @@ -25,8 +27,11 @@ Device-specific notes
>
> The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820.
> If the scx200_acb driver is built into the kernel, add the following
> -parameter to your boot command line:
> +parameter to your boot command line::
> +
> scx200_acb.base=0x810,0x820
> +
> If the scx200_acb driver is built as a module, add the following line to
> -a configuration file in /etc/modprobe.d/ instead:
> +a configuration file in /etc/modprobe.d/ instead::
> +
> options scx200_acb base=0x810,0x820
> diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface.rst
> similarity index 71%
> rename from Documentation/i2c/dev-interface
> rename to Documentation/i2c/dev-interface.rst
> index fbed645ccd75..69c23a3c2b1b 100644
> --- a/Documentation/i2c/dev-interface
> +++ b/Documentation/i2c/dev-interface.rst
> @@ -1,3 +1,7 @@
> +====================
> +I2C Device Interface
> +====================
> +
> Usually, i2c devices are controlled by a kernel driver. But it is also
> possible to access all devices on an adapter from userspace, through
> the /dev interface. You need to load module i2c-dev for this.
> @@ -18,7 +22,7 @@ C example
> =========
>
> So let's say you want to access an i2c adapter from a C program.
> -First, you need to include these two headers:
> +First, you need to include these two headers::
>
> #include <linux/i2c-dev.h>
> #include <i2c/smbus.h>
> @@ -28,7 +32,7 @@ inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
> Adapter numbers are assigned somewhat dynamically, so you can not
> assume much about them. They can even change from one boot to the next.
>
> -Next thing, open the device file, as follows:
> +Next thing, open the device file, as follows::
>
> int file;
> int adapter_nr = 2; /* probably dynamically determined */
> @@ -42,7 +46,7 @@ Next thing, open the device file, as follows:
> }
>
> When you have opened the device, you must specify with what device
> -address you want to communicate:
> +address you want to communicate::
>
> int addr = 0x40; /* The I2C address */
>
> @@ -53,7 +57,7 @@ address you want to communicate:
>
> Well, you are all set up now. You can now use SMBus commands or plain
> I2C to communicate with your device. SMBus commands are preferred if
> -the device supports them. Both are illustrated below.
> +the device supports them. Both are illustrated below::
>
> __u8 reg = 0x10; /* Device register to access */
> __s32 res;
> @@ -100,35 +104,35 @@ Full interface description
>
> The following IOCTLs are defined:
>
> -ioctl(file, I2C_SLAVE, long addr)
> +``ioctl(file, I2C_SLAVE, long addr)``
> Change slave address. The address is passed in the 7 lower bits of the
> argument (except for 10 bit addresses, passed in the 10 lower bits in this
> case).
>
> -ioctl(file, I2C_TENBIT, long select)
> +``ioctl(file, I2C_TENBIT, long select)``
> Selects ten bit addresses if select not equals 0, selects normal 7 bit
> addresses if select equals 0. Default 0. This request is only valid
> if the adapter has I2C_FUNC_10BIT_ADDR.
>
> -ioctl(file, I2C_PEC, long select)
> +``ioctl(file, I2C_PEC, long select)``
> Selects SMBus PEC (packet error checking) generation and verification
> if select not equals 0, disables if select equals 0. Default 0.
> Used only for SMBus transactions. This request only has an effect if the
> the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just
> doesn't have any effect.
>
> -ioctl(file, I2C_FUNCS, unsigned long *funcs)
> - Gets the adapter functionality and puts it in *funcs.
> +``ioctl(file, I2C_FUNCS, unsigned long *funcs)``
> + Gets the adapter functionality and puts it in ``*funcs``.
>
> -ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
> +``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)``
> Do combined read/write transaction without stop in between.
> Only valid if the adapter has I2C_FUNC_I2C. The argument is
> - a pointer to a
> + a pointer to a::
>
> - struct i2c_rdwr_ioctl_data {
> + struct i2c_rdwr_ioctl_data {
> struct i2c_msg *msgs; /* ptr to array of simple messages */
> int nmsgs; /* number of messages to exchange */
> - }
> + }
>
> The msgs[] themselves contain further pointers into data buffers.
> The function will write or read data to or from that buffers depending
> @@ -136,8 +140,8 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
> The slave address and whether to use ten bit address mode has to be
> set in each message, overriding the values set with the above ioctl's.
>
> -ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)
> - If possible, use the provided i2c_smbus_* methods described below instead
> +``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)``
> + If possible, use the provided ``i2c_smbus_*`` methods described below instead
> of issuing direct ioctls.
>
> You can do plain i2c transactions by using read(2) and write(2) calls.
> @@ -145,7 +149,8 @@ You do not need to pass the address byte; instead, set it through
> ioctl I2C_SLAVE before you try to access the device.
>
> You can do SMBus level transactions (see documentation file smbus-protocol
> -for details) through the following functions:
> +for details) through the following functions::
> +
> __s32 i2c_smbus_write_quick(int file, __u8 value);
> __s32 i2c_smbus_read_byte(int file);
> __s32 i2c_smbus_write_byte(int file, __u8 value);
> @@ -157,6 +162,7 @@ for details) through the following functions:
> __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
> __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
> __u8 *values);
> +
> All these transactions return -1 on failure; you can read errno to see
> what happened. The 'write' transactions return 0 on success; the
> 'read' transactions return the read value, except for read_block, which
> @@ -174,39 +180,39 @@ Implementation details
> For the interested, here's the code flow which happens inside the kernel
> when you use the /dev interface to I2C:
>
> -1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in
> -section "C example" above.
> +1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in
> + section "C example" above.
>
> -2* These open() and ioctl() calls are handled by the i2c-dev kernel
> -driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
> -respectively. You can think of i2c-dev as a generic I2C chip driver
> -that can be programmed from user-space.
> +2) These open() and ioctl() calls are handled by the i2c-dev kernel
> + driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
> + respectively. You can think of i2c-dev as a generic I2C chip driver
> + that can be programmed from user-space.
>
> -3* Some ioctl() calls are for administrative tasks and are handled by
> -i2c-dev directly. Examples include I2C_SLAVE (set the address of the
> -device you want to access) and I2C_PEC (enable or disable SMBus error
> -checking on future transactions.)
> +3) Some ioctl() calls are for administrative tasks and are handled by
> + i2c-dev directly. Examples include I2C_SLAVE (set the address of the
> + device you want to access) and I2C_PEC (enable or disable SMBus error
> + checking on future transactions.)
>
> -4* Other ioctl() calls are converted to in-kernel function calls by
> -i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
> -functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
> -performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
> +4) Other ioctl() calls are converted to in-kernel function calls by
> + i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
> + functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
> + performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
>
> -The i2c-dev driver is responsible for checking all the parameters that
> -come from user-space for validity. After this point, there is no
> -difference between these calls that came from user-space through i2c-dev
> -and calls that would have been performed by kernel I2C chip drivers
> -directly. This means that I2C bus drivers don't need to implement
> -anything special to support access from user-space.
> + The i2c-dev driver is responsible for checking all the parameters that
> + come from user-space for validity. After this point, there is no
> + difference between these calls that came from user-space through i2c-dev
> + and calls that would have been performed by kernel I2C chip drivers
> + directly. This means that I2C bus drivers don't need to implement
> + anything special to support access from user-space.
>
> -5* These i2c.h functions are wrappers to the actual implementation of
> -your I2C bus driver. Each adapter must declare callback functions
> -implementing these standard calls. i2c.h:i2c_get_functionality() calls
> -i2c_adapter.algo->functionality(), while
> -i2c-core-smbus.c:i2c_smbus_xfer() calls either
> -adapter.algo->smbus_xfer() if it is implemented, or if not,
> -i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
> -i2c_adapter.algo->master_xfer().
> +5) These i2c.h functions are wrappers to the actual implementation of
> + your I2C bus driver. Each adapter must declare callback functions
> + implementing these standard calls. i2c.h:i2c_get_functionality() calls
> + i2c_adapter.algo->functionality(), while
> + i2c-core-smbus.c:i2c_smbus_xfer() calls either
> + adapter.algo->smbus_xfer() if it is implemented, or if not,
> + i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
> + i2c_adapter.algo->master_xfer().
>
> After your I2C bus driver has processed these requests, execution runs
> up the call chain, with almost no processing done, except by i2c-dev to
> diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/dma-considerations.rst
> similarity index 100%
> rename from Documentation/i2c/DMA-considerations
> rename to Documentation/i2c/dma-considerations.rst
> diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes.rst
> similarity index 98%
> rename from Documentation/i2c/fault-codes
> rename to Documentation/i2c/fault-codes.rst
> index 0cee0fc545b4..a09797588849 100644
> --- a/Documentation/i2c/fault-codes
> +++ b/Documentation/i2c/fault-codes.rst
> @@ -1,3 +1,7 @@
> +=====================
> +I2C/SMBUS Fault Codes
> +=====================
> +
> This is a summary of the most important conventions for use of fault
> codes in the I2C/SMBus stack.
>
> diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality.rst
> similarity index 91%
> rename from Documentation/i2c/functionality
> rename to Documentation/i2c/functionality.rst
> index 4aae8ed15873..7528c1ffd6ca 100644
> --- a/Documentation/i2c/functionality
> +++ b/Documentation/i2c/functionality.rst
> @@ -1,3 +1,7 @@
> +=======================
> +I2C/SMBus Functionality
> +=======================
> +
> INTRODUCTION
> ------------
>
> @@ -14,6 +18,7 @@ FUNCTIONALITY CONSTANTS
> For the most up-to-date list of functionality constants, please check
> <uapi/linux/i2c.h>!
>
> + =============================== ==============================================
> I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus
> adapters typically can not do these)
> I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions
> @@ -33,9 +38,11 @@ For the most up-to-date list of functionality constants, please check
> I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command
> I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command
> I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command
> + =============================== ==============================================
>
> A few combinations of the above flags are also defined for your convenience:
>
> + ========================= ======================================
> I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte
> and write_byte commands
> I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data
> @@ -49,6 +56,7 @@ A few combinations of the above flags are also defined for your convenience:
> I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be
> emulated by a real I2C adapter (using
> the transparent emulation layer)
> + ========================= ======================================
>
> In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as
> part of I2C_FUNC_PROTOCOL_MANGLING.
> @@ -58,11 +66,11 @@ ADAPTER IMPLEMENTATION
> ----------------------
>
> When you write a new adapter driver, you will have to implement a
> -function callback `functionality'. Typical implementations are given
> +function callback ``functionality``. Typical implementations are given
> below.
>
> A typical SMBus-only adapter would list all the SMBus transactions it
> -supports. This example comes from the i2c-piix4 driver:
> +supports. This example comes from the i2c-piix4 driver::
>
> static u32 piix4_func(struct i2c_adapter *adapter)
> {
> @@ -72,7 +80,7 @@ supports. This example comes from the i2c-piix4 driver:
> }
>
> A typical full-I2C adapter would use the following (from the i2c-pxa
> -driver):
> +driver)::
>
> static u32 i2c_pxa_functionality(struct i2c_adapter *adap)
> {
> @@ -94,7 +102,7 @@ CLIENT CHECKING
> Before a client tries to attach to an adapter, or even do tests to check
> whether one of the devices it supports is present on an adapter, it should
> check whether the needed functionality is present. The typical way to do
> -this is (from the lm75 driver):
> +this is (from the lm75 driver)::
>
> static int lm75_detect(...)
> {
> @@ -129,7 +137,7 @@ If you try to access an adapter from a userspace program, you will have
> to use the /dev interface. You will still have to check whether the
> functionality you need is supported, of course. This is done using
> the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is
> -below:
> +below::
>
> int file;
> if (file = open("/dev/i2c-0", O_RDWR) < 0) {
> diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection.rst
> similarity index 97%
> rename from Documentation/i2c/gpio-fault-injection
> rename to Documentation/i2c/gpio-fault-injection.rst
> index c87f416d53dd..9dca6ec7d266 100644
> --- a/Documentation/i2c/gpio-fault-injection
> +++ b/Documentation/i2c/gpio-fault-injection.rst
> @@ -104,10 +104,10 @@ There doesn't need to be a device at this address because arbitration lost
> should be detected beforehand. Also note, that SCL going down is monitored
> using interrupts, so the interrupt latency might cause the first bits to be not
> corrupted. A good starting point for using this fault injector on an otherwise
> -idle bus is:
> +idle bus is::
>
> -# echo 200 > lose_arbitration &
> -# i2cget -y <bus_to_test> 0x3f
> + # echo 200 > lose_arbitration &
> + # i2cget -y <bus_to_test> 0x3f
>
> Panic during transfer
> =====================
> @@ -127,10 +127,10 @@ The calling process will then sleep and wait for the next bus clock. The
> process is interruptible, though.
>
> Start of a transfer is detected by waiting for SCL going down by the master
> -under test. A good starting point for using this fault injector is:
> +under test. A good starting point for using this fault injector is::
>
> -# echo 0 > inject_panic &
> -# i2cget -y <bus_to_test> <some_address>
> + # echo 0 > inject_panic &
> + # i2cget -y <bus_to_test> <some_address>
>
> Note that there doesn't need to be a device listening to the address you are
> using. Results may vary depending on that, though.
> diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol.rst
> similarity index 83%
> rename from Documentation/i2c/i2c-protocol
> rename to Documentation/i2c/i2c-protocol.rst
> index ff6d6cee6c7e..2f8fcf671b2e 100644
> --- a/Documentation/i2c/i2c-protocol
> +++ b/Documentation/i2c/i2c-protocol.rst
> @@ -1,8 +1,13 @@
> +============
> +I2C Protocol
> +============
> +
> This document describes the i2c protocol. Or will, when it is finished :-)
>
> Key to symbols
> ==============
>
> +=============== =============================================================
> S (1 bit) : Start bit
> P (1 bit) : Stop bit
> Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
> @@ -15,33 +20,35 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
> for 16 bit data.
> Count (8 bits): A data byte containing the length of a block operation.
>
> -[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
> +[..]: Data sent by I2C device, as opposed to data sent by the
> + host adapter.
> +=============== =============================================================
>
>
> Simple send transaction
> -======================
> +=======================
>
> -This corresponds to i2c_master_send.
> +This corresponds to i2c_master_send::
>
> S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
>
>
> Simple receive transaction
> -===========================
> +==========================
>
> -This corresponds to i2c_master_recv
> +This corresponds to i2c_master_recv::
>
> S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
>
>
> Combined transactions
> -====================
> +=====================
>
> This corresponds to i2c_transfer
>
> They are just like the above transactions, but instead of a stop bit P
> a start bit S is sent and the transaction continues. An example of
> -a byte read, followed by a byte write:
> +a byte read, followed by a byte write::
>
> S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
>
> @@ -65,8 +72,10 @@ I2C_M_NO_RD_ACK:
> I2C_M_NOSTART:
> In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
> point. For example, setting I2C_M_NOSTART on the second partial message
> - generates something like:
> + generates something like::
> +
> S Addr Rd [A] [Data] NA Data [A] P
> +
> If you set the I2C_M_NOSTART variable for the first partial message,
> we do not generate Addr, but we do generate the startbit S. This will
> probably confuse all other clients on your bus, so don't try this.
> @@ -79,7 +88,8 @@ I2C_M_NOSTART:
> I2C_M_REV_DIR_ADDR:
> This toggles the Rd/Wr flag. That is, if you want to do a write, but
> need to emit an Rd instead of a Wr, or vice versa, you set this
> - flag. For example:
> + flag. For example::
> +
> S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
>
> I2C_M_STOP:
> diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub.rst
> similarity index 93%
> rename from Documentation/i2c/i2c-stub
> rename to Documentation/i2c/i2c-stub.rst
> index a16924fbd289..f8f194dfd379 100644
> --- a/Documentation/i2c/i2c-stub
> +++ b/Documentation/i2c/i2c-stub.rst
> @@ -1,6 +1,9 @@
> -MODULE: i2c-stub
> +========
> +i2c-stub
> +========
>
> -DESCRIPTION:
> +Description
> +===========
>
> This module is a very simple fake I2C/SMBus driver. It implements six
> types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w)
> @@ -28,6 +31,7 @@ SMBus block operations. Writes can be partial. Block read commands always
> return the number of bytes selected with the largest write so far.
>
> The typical use-case is like this:
> +
> 1. load this module
> 2. use i2cset (from the i2c-tools project) to pre-load some data
> 3. load the target chip driver module
> @@ -36,7 +40,8 @@ The typical use-case is like this:
> There's a script named i2c-stub-from-dump in the i2c-tools package which
> can load register values automatically from a chip dump.
>
> -PARAMETERS:
> +Parameters
> +==========
>
> int chip_addr[10]:
> The SMBus addresses to emulate chips at.
> @@ -47,14 +52,12 @@ unsigned long functionality:
> value 0x1f0000 would only enable the quick, byte and byte data
> commands.
>
> -u8 bank_reg[10]
> -u8 bank_mask[10]
> -u8 bank_start[10]
> -u8 bank_end[10]:
> +u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]:
> Optional bank settings. They tell which bits in which register
> select the active bank, as well as the range of banked registers.
>
> -CAVEATS:
> +Caveats
> +=======
>
> If your target driver polls some byte or word waiting for it to change, the
> stub could lock it up. Use i2cset to unlock it.
> diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology.rst
> similarity index 89%
> rename from Documentation/i2c/i2c-topology
> rename to Documentation/i2c/i2c-topology.rst
> index f74d78b53d4d..0c1ae95f6a97 100644
> --- a/Documentation/i2c/i2c-topology
> +++ b/Documentation/i2c/i2c-topology.rst
> @@ -1,3 +1,4 @@
> +============
> I2C topology
> ============
>
> @@ -14,6 +15,7 @@ than a straight-forward i2c bus with one adapter and one or more devices.
> that has to be operated before the device can be accessed.
>
> Etc
> +===
>
> These constructs are represented as i2c adapter trees by Linux, where
> each adapter has a parent adapter (except the root adapter) and zero or
> @@ -37,7 +39,9 @@ mux-locked or parent-locked muxes. As is evident from below, it can be
> useful to know if a mux is mux-locked or if it is parent-locked. The
> following list was correct at the time of writing:
>
> -In drivers/i2c/muxes/
> +In drivers/i2c/muxes/:
> +
> +====================== =============================================
> i2c-arb-gpio-challenge Parent-locked
> i2c-mux-gpio Normally parent-locked, mux-locked iff
> all involved gpio pins are controlled by the
> @@ -52,18 +56,25 @@ i2c-mux-pinctrl Normally parent-locked, mux-locked iff
> all involved pinctrl devices are controlled
> by the same i2c root adapter that they mux.
> i2c-mux-reg Parent-locked
> +====================== =============================================
>
> -In drivers/iio/
> +In drivers/iio/:
> +
> +====================== =============================================
> gyro/mpu3050 Mux-locked
> imu/inv_mpu6050/ Mux-locked
> +====================== =============================================
>
> -In drivers/media/
> +In drivers/media/:
> +
> +======================= =============================================
> dvb-frontends/lgdt3306a Mux-locked
> dvb-frontends/m88ds3103 Parent-locked
> dvb-frontends/rtl2830 Parent-locked
> dvb-frontends/rtl2832 Mux-locked
> dvb-frontends/si2168 Mux-locked
> usb/cx231xx/ Parent-locked
> +======================= =============================================
>
>
> Mux-locked muxes
> @@ -78,6 +89,7 @@ full transaction, unrelated i2c transfers may interleave the different
> stages of the transaction. This has the benefit that the mux driver
> may be easier and cleaner to implement, but it has some caveats.
>
> +==== =====================================================================
> ML1. If you build a topology with a mux-locked mux being the parent
> of a parent-locked mux, this might break the expectation from the
> parent-locked mux that the root adapter is locked during the
> @@ -105,11 +117,15 @@ ML4. If any non-i2c operation in the mux driver changes the i2c mux state,
> Otherwise garbage may appear on the bus as seen from devices
> behind the mux, when an unrelated i2c transfer is in flight during
> the non-i2c mux-changing operation.
> +==== =====================================================================
>
>
> Mux-locked Example
> ------------------
>
> +
> +::
> +
> .----------. .--------.
> .--------. | mux- |-----| dev D1 |
> | root |--+--| locked | '--------'
> @@ -148,6 +164,7 @@ adapter during the transaction are unlocked i2c transfers (using e.g.
> __i2c_transfer), or a deadlock will follow. There are a couple of
> caveats.
>
> +==== ====================================================================
> PL1. If you build a topology with a parent-locked mux being the child
> of another mux, this might break a possible assumption from the
> child mux that the root adapter is unused between its select op
> @@ -161,11 +178,14 @@ PL2. If select/deselect calls out to other subsystems such as gpio,
> caused by these subsystems are unlocked. This can be convoluted to
> accomplish, maybe even impossible if an acceptably clean solution
> is sought.
> +==== ====================================================================
>
>
> Parent-locked Example
> ---------------------
>
> +::
> +
> .----------. .--------.
> .--------. | parent- |-----| dev D1 |
> | root |--+--| locked | '--------'
> @@ -177,20 +197,20 @@ Parent-locked Example
>
> When there is an access to D1, this happens:
>
> - 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
> - 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
> - adapter.
> - 7. M1 calls ->deselect, if it has one.
> - 8. Same rules as in step 5, but for ->deselect.
> - 9. M1 unlocks its parent adapter.
> -10. M1 unlocks muxes on its parent.
> + 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
> + 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
> + adapter.
> + 7. M1 calls ->deselect, if it has one.
> + 8. Same rules as in step 5, but for ->deselect.
> + 9. M1 unlocks its parent adapter.
> + 10. M1 unlocks muxes on its parent.
>
>
> This means that accesses to both D2 and D3 are locked out for the full
> @@ -203,7 +223,7 @@ Complex Examples
> Parent-locked mux as parent of parent-locked mux
> ------------------------------------------------
>
> -This is a useful topology, but it can be bad.
> +This is a useful topology, but it can be bad::
>
> .----------. .----------. .--------.
> .--------. | parent- |-----| parent- |-----| dev D1 |
> @@ -227,7 +247,7 @@ through and be seen by the M2 adapter, thus closing M2 prematurely.
> Mux-locked mux as parent of mux-locked mux
> ------------------------------------------
>
> -This is a good topology.
> +This is a good topology::
>
> .----------. .----------. .--------.
> .--------. | mux- |-----| mux- |-----| dev D1 |
> @@ -248,7 +268,7 @@ are still possibly interleaved.
> Mux-locked mux as parent of parent-locked mux
> ---------------------------------------------
>
> -This is probably a bad topology.
> +This is probably a bad topology::
>
> .----------. .----------. .--------.
> .--------. | mux- |-----| parent- |-----| dev D1 |
> @@ -282,7 +302,7 @@ auto-closing, the topology is fine.
> Parent-locked mux as parent of mux-locked mux
> ---------------------------------------------
>
> -This is a good topology.
> +This is a good topology::
>
> .----------. .----------. .--------.
> .--------. | parent- |-----| mux- |-----| dev D1 |
> @@ -306,7 +326,7 @@ adapter is locked directly.
> Two mux-locked sibling muxes
> ----------------------------
>
> -This is a good topology.
> +This is a good topology::
>
> .--------.
> .----------. .--| dev D1 |
> @@ -330,7 +350,7 @@ accesses to D5 may be interleaved at any time.
> Two parent-locked sibling muxes
> -------------------------------
>
> -This is a good topology.
> +This is a good topology::
>
> .--------.
> .----------. .--| dev D1 |
> @@ -354,7 +374,7 @@ out.
> Mux-locked and parent-locked sibling muxes
> ------------------------------------------
>
> -This is a good topology.
> +This is a good topology::
>
> .--------.
> .----------. .--| dev D1 |
> diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
> new file mode 100644
> index 000000000000..d4ba671d0b55
> --- /dev/null
> +++ b/Documentation/i2c/index.rst
> @@ -0,0 +1,38 @@
> +. SPDX-License-Identifier: GPL-2.0
> +
> +===================
> +I2C/SMBus Subsystem
> +===================
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + dev-interface
> + dma-considerations
> + fault-codes
> + functionality
> + gpio-fault-injection
> + i2c-protocol
> + i2c-stub
> + i2c-topology
> + instantiating-devices
> + old-module-parameters
> + slave-eeprom-backend
> + slave-interface
> + smbus-protocol
> + summary
> + ten-bit-addresses
> + upgrading-clients
> + writing-clients
> +
> + muxes/i2c-mux-gpio
> +
> + busses/index
> +
> +.. only:: subproject and html
> +
> + Indices
> + =======
> +
> + * :ref:`genindex`
> +
> diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices.rst
> similarity index 93%
> rename from Documentation/i2c/instantiating-devices
> rename to Documentation/i2c/instantiating-devices.rst
> index 345e9ea8281a..1238f1fa3382 100644
> --- a/Documentation/i2c/instantiating-devices
> +++ b/Documentation/i2c/instantiating-devices.rst
> @@ -1,3 +1,4 @@
> +==============================
> How to instantiate I2C devices
> ==============================
>
> @@ -17,9 +18,9 @@ which is known in advance. It is thus possible to pre-declare the I2C
> devices which live on this bus. This is done with an array of struct
> i2c_board_info which is registered by calling i2c_register_board_info().
>
> -Example (from omap2 h4):
> +Example (from omap2 h4)::
>
> -static struct i2c_board_info h4_i2c_board_info[] __initdata = {
> + static struct i2c_board_info h4_i2c_board_info[] __initdata = {
> {
> I2C_BOARD_INFO("isp1301_omap", 0x2d),
> .irq = OMAP_GPIO_IRQ(125),
> @@ -32,15 +33,15 @@ static struct i2c_board_info h4_i2c_board_info[] __initdata = {
> I2C_BOARD_INFO("24c01", 0x57),
> .platform_data = &m24c01,
> },
> -};
> + };
>
> -static void __init omap_h4_init(void)
> -{
> + static void __init omap_h4_init(void)
> + {
> (...)
> i2c_register_board_info(1, h4_i2c_board_info,
> ARRAY_SIZE(h4_i2c_board_info));
> (...)
> -}
> + }
>
> The above code declares 3 devices on I2C bus 1, including their respective
> addresses and custom data needed by their drivers. When the I2C bus in
> @@ -57,7 +58,7 @@ Method 1b: Declare the I2C devices via devicetree
> This method has the same implications as method 1a. The declaration of I2C
> devices is here done via devicetree as subnodes of the master controller.
>
> -Example:
> +Example::
>
> i2c1: i2c@400a0000 {
> /* ... master properties skipped ... */
> @@ -99,20 +100,20 @@ bus in advance, so the method 1 described above can't be used. Instead,
> you can instantiate your I2C devices explicitly. This is done by filling
> a struct i2c_board_info and calling i2c_new_device().
>
> -Example (from the sfe4001 network driver):
> +Example (from the sfe4001 network driver)::
>
> -static struct i2c_board_info sfe4001_hwmon_info = {
> + static struct i2c_board_info sfe4001_hwmon_info = {
> I2C_BOARD_INFO("max6647", 0x4e),
> -};
> + };
>
> -int sfe4001_init(struct efx_nic *efx)
> -{
> + int sfe4001_init(struct efx_nic *efx)
> + {
> (...)
> efx->board_info.hwmon_client =
> i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info);
>
> (...)
> -}
> + }
>
> The above code instantiates 1 I2C device on the I2C bus which is on the
> network adapter in question.
> @@ -124,12 +125,12 @@ it may have different addresses from one board to the next (manufacturer
> changing its design without notice). In this case, you can call
> i2c_new_probed_device() instead of i2c_new_device().
>
> -Example (from the nxp OHCI driver):
> +Example (from the nxp OHCI driver)::
>
> -static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
> + static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
>
> -static int usb_hcd_nxp_probe(struct platform_device *pdev)
> -{
> + static int usb_hcd_nxp_probe(struct platform_device *pdev)
> + {
> (...)
> struct i2c_adapter *i2c_adap;
> struct i2c_board_info i2c_info;
> @@ -142,7 +143,7 @@ static int usb_hcd_nxp_probe(struct platform_device *pdev)
> normal_i2c, NULL);
> i2c_put_adapter(i2c_adap);
> (...)
> -}
> + }
>
> The above code instantiates up to 1 I2C device on the I2C bus which is on
> the OHCI adapter in question. It first tries at address 0x2c, if nothing
> @@ -172,6 +173,7 @@ explicitly. Instead, i2c-core will probe for such devices as soon as their
> drivers are loaded, and if any is found, an I2C device will be
> instantiated automatically. In order to prevent any misbehavior of this
> mechanism, the following restrictions apply:
> +
> * The I2C device driver must implement the detect() method, which
> identifies a supported device by reading from arbitrary registers.
> * Only buses which are likely to have a supported device and agree to be
> @@ -189,6 +191,7 @@ first.
> Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6
> kernels will find out that this method 3 is essentially similar to what
> was done there. Two significant differences are:
> +
> * Probing is only one way to instantiate I2C devices now, while it was the
> only way back then. Where possible, methods 1 and 2 should be preferred.
> Method 3 should only be used when there is no other way, as it can have
> @@ -224,11 +227,13 @@ device. As no two devices can live at the same address on a given I2C
> segment, the address is sufficient to uniquely identify the device to be
> deleted.
>
> -Example:
> -# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
> +Example::
> +
> + # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
>
> While this interface should only be used when in-kernel device declaration
> can't be done, there is a variety of cases where it can be helpful:
> +
> * The I2C driver usually detects devices (method 3 above) but the bus
> segment your device lives on doesn't have the proper class bit set and
> thus detection doesn't trigger.
> diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio.rst
> similarity index 85%
> rename from Documentation/i2c/muxes/i2c-mux-gpio
> rename to Documentation/i2c/muxes/i2c-mux-gpio.rst
> index 893ecdfe6e43..7d27444035c3 100644
> --- a/Documentation/i2c/muxes/i2c-mux-gpio
> +++ b/Documentation/i2c/muxes/i2c-mux-gpio.rst
> @@ -1,4 +1,6 @@
> +==========================
> Kernel driver i2c-mux-gpio
> +==========================
>
> Author: Peter Korsgaard <peter.korsgaard@barco.com>
>
> @@ -8,7 +10,7 @@ Description
> i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments
> from a master I2C bus and a hardware MUX controlled through GPIO pins.
>
> -E.G.:
> +E.G.::
>
> ---------- ---------- Bus segment 1 - - - - -
> | | SCL/SDA | |-------------- | |
> @@ -33,20 +35,20 @@ bus, the number of bus segments to create and the GPIO pins used
> to control it. See include/linux/platform_data/i2c-mux-gpio.h for details.
>
> E.G. something like this for a MUX providing 4 bus segments
> -controlled through 3 GPIO pins:
> +controlled through 3 GPIO pins::
>
> -#include <linux/platform_data/i2c-mux-gpio.h>
> -#include <linux/platform_device.h>
> + #include <linux/platform_data/i2c-mux-gpio.h>
> + #include <linux/platform_device.h>
>
> -static const unsigned myboard_gpiomux_gpios[] = {
> + static const unsigned myboard_gpiomux_gpios[] = {
> AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24
> -};
> + };
>
> -static const unsigned myboard_gpiomux_values[] = {
> + static const unsigned myboard_gpiomux_values[] = {
> 0, 1, 2, 3
> -};
> + };
>
> -static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
> + static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
> .parent = 1,
> .base_nr = 2, /* optional */
> .values = myboard_gpiomux_values,
> @@ -54,15 +56,15 @@ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
> .gpios = myboard_gpiomux_gpios,
> .n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios),
> .idle = 4, /* optional */
> -};
> + };
>
> -static struct platform_device myboard_i2cmux = {
> + static struct platform_device myboard_i2cmux = {
> .name = "i2c-mux-gpio",
> .id = 0,
> .dev = {
> .platform_data = &myboard_i2cmux_data,
> },
> -};
> + };
>
> If you don't know the absolute GPIO pin numbers at registration time,
> you can instead provide a chip name (.chip_name) and relative GPIO pin
> diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters.rst
> similarity index 75%
> rename from Documentation/i2c/old-module-parameters
> rename to Documentation/i2c/old-module-parameters.rst
> index 8e2b629d533c..a1939512ad66 100644
> --- a/Documentation/i2c/old-module-parameters
> +++ b/Documentation/i2c/old-module-parameters.rst
> @@ -1,3 +1,4 @@
> +=================================================
> I2C device driver binding control from user-space
> =================================================
>
> @@ -19,23 +20,27 @@ Below is a mapping from the old module parameters to the new interface.
> Attaching a driver to an I2C device
> -----------------------------------
>
> -Old method (module parameters):
> -# modprobe <driver> probe=1,0x2d
> -# modprobe <driver> force=1,0x2d
> -# modprobe <driver> force_<device>=1,0x2d
> +Old method (module parameters)::
>
> -New method (sysfs interface):
> -# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
> + # modprobe <driver> probe=1,0x2d
> + # modprobe <driver> force=1,0x2d
> + # modprobe <driver> force_<device>=1,0x2d
> +
> +New method (sysfs interface)::
> +
> + # echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
>
> Preventing a driver from attaching to an I2C device
> ---------------------------------------------------
>
> -Old method (module parameters):
> -# modprobe <driver> ignore=1,0x2f
> +Old method (module parameters)::
>
> -New method (sysfs interface):
> -# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
> -# modprobe <driver>
> + # modprobe <driver> ignore=1,0x2f
> +
> +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
> the driver. The dummy device will be handled by i2c-core itself, preventing
> diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend.rst
> similarity index 90%
> rename from Documentation/i2c/slave-eeprom-backend
> rename to Documentation/i2c/slave-eeprom-backend.rst
> index 04f8d8a9b817..2018fa74c6f3 100644
> --- a/Documentation/i2c/slave-eeprom-backend
> +++ b/Documentation/i2c/slave-eeprom-backend.rst
> @@ -1,3 +1,4 @@
> +==============================
> Linux I2C slave eeprom backend
> ==============================
>
> @@ -5,7 +6,7 @@ by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
>
> This is a proof-of-concept backend which acts like an EEPROM on the connected
> I2C bus. The memory contents can be modified from userspace via this file
> -located in sysfs:
> +located in sysfs::
>
> /sys/bus/i2c/devices/<device-directory>/slave-eeprom
>
> diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface.rst
> similarity index 94%
> rename from Documentation/i2c/slave-interface
> rename to Documentation/i2c/slave-interface.rst
> index 7e2a228f21bc..9ac5f110a4ec 100644
> --- a/Documentation/i2c/slave-interface
> +++ b/Documentation/i2c/slave-interface.rst
> @@ -1,3 +1,4 @@
> +=====================================
> Linux I2C slave interface description
> =====================================
>
> @@ -12,7 +13,7 @@ EEPROM, the Linux I2C slave can access the content via sysfs and handle data as
> needed. The backend driver and the I2C bus driver communicate via events. Here
> is a small graph visualizing the data flow and the means by which data is
> transported. The dotted line marks only one example. The backend could also
> -use a character device, be in-kernel only, or something completely different:
> +use a character device, be in-kernel only, or something completely different::
>
>
> e.g. sysfs I2C slave events I/O registers
> @@ -35,7 +36,7 @@ them as described in the document 'instantiating-devices'. The only difference
> is that i2c slave backends have their own address space. So, you have to add
> 0x1000 to the address you would originally request. An example for
> instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64
> -on bus 1:
> +on bus 1::
>
> # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device
>
> @@ -54,7 +55,7 @@ drivers and writing backends will be given.
> I2C slave events
> ----------------
>
> -The bus driver sends an event to the backend using the following function:
> +The bus driver sends an event to the backend using the following function::
>
> ret = i2c_slave_event(client, event, &val)
>
> @@ -69,8 +70,9 @@ Event types:
>
> * I2C_SLAVE_WRITE_REQUESTED (mandatory)
>
> -'val': unused
> -'ret': always 0
> + 'val': unused
> +
> + 'ret': always 0
>
> Another I2C master wants to write data to us. This event should be sent once
> our own address and the write bit was detected. The data did not arrive yet, so
> @@ -79,8 +81,9 @@ to be done, though.
>
> * I2C_SLAVE_READ_REQUESTED (mandatory)
>
> -'val': backend returns first byte to be sent
> -'ret': always 0
> + 'val': backend returns first byte to be sent
> +
> + 'ret': always 0
>
> Another I2C master wants to read data from us. This event should be sent once
> our own address and the read bit was detected. After returning, the bus driver
> @@ -88,8 +91,9 @@ should transmit the first byte.
>
> * I2C_SLAVE_WRITE_RECEIVED (mandatory)
>
> -'val': bus driver delivers received byte
> -'ret': 0 if the byte should be acked, some errno if the byte should be nacked
> + 'val': bus driver delivers received byte
> +
> + 'ret': 0 if the byte should be acked, some errno if the byte should be nacked
>
> Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
> is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
> @@ -97,8 +101,9 @@ should be nacked.
>
> * I2C_SLAVE_READ_PROCESSED (mandatory)
>
> -'val': backend returns next byte to be sent
> -'ret': always 0
> + 'val': backend returns next byte to be sent
> +
> + 'ret': always 0
>
> The bus driver requests the next byte to be sent to another I2C master in
> 'val'. Important: This does not mean that the previous byte has been acked, it
> @@ -111,8 +116,9 @@ your backend, though.
>
> * I2C_SLAVE_STOP (mandatory)
>
> -'val': unused
> -'ret': always 0
> + 'val': unused
> +
> + 'ret': always 0
>
> A stop condition was received. This can happen anytime and the backend should
> reset its state machine for I2C transfers to be able to receive new requests.
> diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol.rst
> similarity index 84%
> rename from Documentation/i2c/smbus-protocol
> rename to Documentation/i2c/smbus-protocol.rst
> index 092d474f5843..c6f189bfe1c7 100644
> --- a/Documentation/i2c/smbus-protocol
> +++ b/Documentation/i2c/smbus-protocol.rst
> @@ -1,3 +1,4 @@
> +======================
> SMBus Protocol Summary
> ======================
>
> @@ -27,12 +28,13 @@ Each transaction type corresponds to a functionality flag. Before calling a
> transaction function, a device driver should always check (just once) for
> the corresponding functionality flag to ensure that the underlying I2C
> adapter supports the transaction in question. See
> -<file:Documentation/i2c/functionality> for the details.
> +<file:Documentation/i2c/functionality.rst> for the details.
>
>
> Key to symbols
> ==============
>
> +=============== =============================================================
> S (1 bit) : Start bit
> P (1 bit) : Stop bit
> Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
> @@ -45,15 +47,17 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
> for 16 bit data.
> Count (8 bits): A data byte containing the length of a block operation.
>
> -[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
> +[..]: Data sent by I2C device, as opposed to data sent by the host
> + adapter.
> +=============== =============================================================
>
>
> SMBus Quick Command
> ===================
>
> -This sends a single bit to the device, at the place of the Rd/Wr bit.
> +This sends a single bit to the device, at the place of the Rd/Wr bit::
>
> -A Addr Rd/Wr [A] P
> + A Addr Rd/Wr [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_QUICK
>
> @@ -64,9 +68,9 @@ SMBus Receive Byte: i2c_smbus_read_byte()
> This reads a single byte from a device, without specifying a device
> register. Some devices are so simple that this interface is enough; for
> others, it is a shorthand if you want to read the same register as in
> -the previous SMBus command.
> +the previous SMBus command::
>
> -S Addr Rd [A] [Data] NA P
> + S Addr Rd [A] [Data] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_READ_BYTE
>
> @@ -77,7 +81,9 @@ SMBus Send Byte: i2c_smbus_write_byte()
> This operation is the reverse of Receive Byte: it sends a single byte
> to a device. See Receive Byte for more information.
>
> -S Addr Wr [A] Data [A] P
> +::
> +
> + S Addr Wr [A] Data [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE
>
> @@ -86,9 +92,9 @@ SMBus Read Byte: i2c_smbus_read_byte_data()
> ============================================
>
> This reads a single byte from a device, from a designated register.
> -The register is specified through the Comm byte.
> +The register is specified through the Comm byte::
>
> -S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
> + S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA
>
> @@ -98,9 +104,9 @@ SMBus Read Word: i2c_smbus_read_word_data()
>
> This operation is very like Read Byte; again, data is read from a
> device, from a designated register that is specified through the Comm
> -byte. But this time, the data is a complete word (16 bits).
> +byte. But this time, the data is a complete word (16 bits)::
>
> -S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
> + S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA
>
> @@ -116,7 +122,9 @@ This writes a single byte to a device, to a designated register. The
> register is specified through the Comm byte. This is the opposite of
> the Read Byte operation.
>
> -S Addr Wr [A] Comm [A] Data [A] P
> +::
> +
> + S Addr Wr [A] Comm [A] Data [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA
>
> @@ -126,9 +134,9 @@ SMBus Write Word: i2c_smbus_write_word_data()
>
> This is the opposite of the Read Word operation. 16 bits
> of data is written to a device, to the designated register that is
> -specified through the Comm byte.
> +specified through the Comm byte.::
>
> -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
> + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA
>
> @@ -141,10 +149,10 @@ SMBus Process Call:
> ===================
>
> This command selects a device register (through the Comm byte), sends
> -16 bits of data to it, and reads 16 bits of data in return.
> +16 bits of data to it, and reads 16 bits of data in return::
>
> -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
> - S Addr Rd [A] [DataLow] A [DataHigh] NA P
> + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
> + S Addr Rd [A] [DataLow] A [DataHigh] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
>
> @@ -156,8 +164,10 @@ This command reads a block of up to 32 bytes from a device, from a
> designated register that is specified through the Comm byte. The amount
> of data is specified by the device in the Count byte.
>
> -S Addr Wr [A] Comm [A]
> - S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
> +::
> +
> + S Addr Wr [A] Comm [A]
> + S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
>
> @@ -169,7 +179,9 @@ The opposite of the Block Read command, this writes up to 32 bytes to
> a device, to a designated register that is specified through the
> Comm byte. The amount of data is specified in the Count byte.
>
> -S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
> +::
> +
> + S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA
>
> @@ -181,10 +193,10 @@ SMBus Block Write - Block Read Process Call was introduced in
> Revision 2.0 of the specification.
>
> This command selects a device register (through the Comm byte), sends
> -1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return.
> +1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return::
>
> -S Addr Wr [A] Comm [A] Count [A] Data [A] ...
> - S Addr Rd [A] [Count] A [Data] ... A P
> + S Addr Wr [A] Comm [A] Count [A] Data [A] ...
> + S Addr Rd [A] [Count] A [Data] ... A P
>
> Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL
>
> @@ -197,9 +209,12 @@ SMBus host acting as a slave.
> It is the same form as Write Word, with the command code replaced by the
> alerting device's address.
>
> -[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
> +::
> +
> + [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
>
> This is implemented in the following way in the Linux kernel:
> +
> * I2C bus drivers which support SMBus Host Notify should report
> I2C_FUNC_SMBUS_HOST_NOTIFY.
> * I2C bus drivers trigger SMBus Host Notify by a call to
> @@ -241,6 +256,7 @@ single interrupt pin on the SMBus master, while still allowing the master
> to know which slave triggered the interrupt.
>
> This is implemented the following way in the Linux kernel:
> +
> * I2C bus drivers which support SMBus alert should call
> i2c_setup_smbus_alert() to setup SMBus alert support.
> * I2C drivers for devices which can trigger SMBus alerts should implement
> @@ -262,10 +278,10 @@ I2C Block Read: i2c_smbus_read_i2c_block_data()
> ================================================
>
> This command reads a block of bytes from a device, from a
> -designated register that is specified through the Comm byte.
> +designated register that is specified through the Comm byte::
>
> -S Addr Wr [A] Comm [A]
> - S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
> + S Addr Wr [A] Comm [A]
> + S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
>
> @@ -278,6 +294,8 @@ a device, to a designated register that is specified through the
> Comm byte. Note that command lengths of 0, 2, or more bytes are
> supported as they are indistinguishable from data.
>
> -S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
> +::
> +
> + S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK
> diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary.rst
> similarity index 96%
> rename from Documentation/i2c/summary
> rename to Documentation/i2c/summary.rst
> index 809541ab352f..8c08fa727f4e 100644
> --- a/Documentation/i2c/summary
> +++ b/Documentation/i2c/summary.rst
> @@ -1,3 +1,4 @@
> +=============
> I2C and SMBus
> =============
>
> @@ -24,7 +25,8 @@ implement all the common SMBus protocol semantics or messages.
> Terminology
> ===========
>
> -When we talk about I2C, we use the following terms:
> +When we talk about I2C, we use the following terms::
> +
> Bus -> Algorithm
> Adapter
> Device -> Driver
> diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses.rst
> similarity index 95%
> rename from Documentation/i2c/ten-bit-addresses
> rename to Documentation/i2c/ten-bit-addresses.rst
> index 7b2d11e53a49..5c765aff16d5 100644
> --- a/Documentation/i2c/ten-bit-addresses
> +++ b/Documentation/i2c/ten-bit-addresses.rst
> @@ -1,3 +1,7 @@
> +=====================
> +I2C Ten-bit Addresses
> +=====================
> +
> The I2C protocol knows about two kinds of device addresses: normal 7 bit
> addresses, and an extended set of 10 bit addresses. The sets of addresses
> do not intersect: the 7 bit address 0x10 is not the same as the 10 bit
> @@ -12,6 +16,7 @@ See the I2C specification for the details.
>
> The current 10 bit address support is minimal. It should work, however
> you can expect some problems along the way:
> +
> * Not all bus drivers support 10-bit addresses. Some don't because the
> hardware doesn't support them (SMBus doesn't require 10-bit address
> support for example), some don't because nobody bothered adding the
> diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients.rst
> similarity index 56%
> rename from Documentation/i2c/upgrading-clients
> rename to Documentation/i2c/upgrading-clients.rst
> index 96392cc5b5c7..4a575e607ff8 100644
> --- a/Documentation/i2c/upgrading-clients
> +++ b/Documentation/i2c/upgrading-clients.rst
> @@ -1,3 +1,4 @@
> +=================================================
> Upgrading I2C Drivers to the new 2.6 Driver Model
> =================================================
>
> @@ -13,21 +14,22 @@ the old to the new new binding methods.
> Example old-style driver
> ------------------------
>
> +::
>
> -struct example_state {
> + struct example_state {
> struct i2c_client client;
> ....
> -};
> + };
>
> -static struct i2c_driver example_driver;
> + static struct i2c_driver example_driver;
>
> -static unsigned short ignore[] = { I2C_CLIENT_END };
> -static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
> + static unsigned short ignore[] = { I2C_CLIENT_END };
> + static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
>
> -I2C_CLIENT_INSMOD;
> + I2C_CLIENT_INSMOD;
>
> -static int example_attach(struct i2c_adapter *adap, int addr, int kind)
> -{
> + static int example_attach(struct i2c_adapter *adap, int addr, int kind)
> + {
> struct example_state *state;
> struct device *dev = &adap->dev; /* to use for dev_ reports */
> int ret;
> @@ -59,23 +61,23 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind)
> dev_info(dev, "example client created\n");
>
> return 0;
> -}
> + }
>
> -static int example_detach(struct i2c_client *client)
> -{
> + static int example_detach(struct i2c_client *client)
> + {
> struct example_state *state = i2c_get_clientdata(client);
>
> i2c_detach_client(client);
> kfree(state);
> return 0;
> -}
> + }
>
> -static int example_attach_adapter(struct i2c_adapter *adap)
> -{
> + static int example_attach_adapter(struct i2c_adapter *adap)
> + {
> return i2c_probe(adap, &addr_data, example_attach);
> -}
> + }
>
> -static struct i2c_driver example_driver = {
> + static struct i2c_driver example_driver = {
> .driver = {
> .owner = THIS_MODULE,
> .name = "example",
> @@ -83,7 +85,7 @@ static struct i2c_driver example_driver = {
> },
> .attach_adapter = example_attach_adapter,
> .detach_client = example_detach,
> -};
> + };
>
>
> Updating the client
> @@ -93,38 +95,38 @@ The new style binding model will check against a list of supported
> devices and their associated address supplied by the code registering
> the busses. This means that the driver .attach_adapter and
> .detach_client methods can be removed, along with the addr_data,
> -as follows:
> +as follows::
>
> -- static struct i2c_driver example_driver;
> + - static struct i2c_driver example_driver;
>
> -- static unsigned short ignore[] = { I2C_CLIENT_END };
> -- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
> + - static unsigned short ignore[] = { I2C_CLIENT_END };
> + - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
>
> -- I2C_CLIENT_INSMOD;
> + - I2C_CLIENT_INSMOD;
>
> -- static int example_attach_adapter(struct i2c_adapter *adap)
> -- {
> -- return i2c_probe(adap, &addr_data, example_attach);
> -- }
> + - static int example_attach_adapter(struct i2c_adapter *adap)
> + - {
> + - return i2c_probe(adap, &addr_data, example_attach);
> + - }
>
> - static struct i2c_driver example_driver = {
> -- .attach_adapter = example_attach_adapter,
> -- .detach_client = example_detach,
> - }
> + static struct i2c_driver example_driver = {
> + - .attach_adapter = example_attach_adapter,
> + - .detach_client = example_detach,
> + }
>
> -Add the probe and remove methods to the i2c_driver, as so:
> +Add the probe and remove methods to the i2c_driver, as so::
>
> - static struct i2c_driver example_driver = {
> -+ .probe = example_probe,
> -+ .remove = example_remove,
> - }
> + static struct i2c_driver example_driver = {
> + + .probe = example_probe,
> + + .remove = example_remove,
> + }
>
> Change the example_attach method to accept the new parameters
> -which include the i2c_client that it will be working with:
> +which include the i2c_client that it will be working with::
>
> -- static int example_attach(struct i2c_adapter *adap, int addr, int kind)
> -+ static int example_probe(struct i2c_client *client,
> -+ const struct i2c_device_id *id)
> + - static int example_attach(struct i2c_adapter *adap, int addr, int kind)
> + + static int example_probe(struct i2c_client *client,
> + + const struct i2c_device_id *id)
>
> Change the name of example_attach to example_probe to align it with the
> i2c_driver entry names. The rest of the probe routine will now need to be
> @@ -132,55 +134,57 @@ changed as the i2c_client has already been setup for use.
>
> The necessary client fields have already been setup before
> the probe function is called, so the following client setup
> -can be removed:
> +can be removed::
>
> -- example->client.addr = addr;
> -- example->client.flags = 0;
> -- example->client.adapter = adap;
> --
> -- strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
> + - example->client.addr = addr;
> + - example->client.flags = 0;
> + - example->client.adapter = adap;
> + -
> + - strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
>
> -The i2c_set_clientdata is now:
> +The i2c_set_clientdata is now::
>
> -- i2c_set_clientdata(&state->client, state);
> -+ i2c_set_clientdata(client, state);
> + - i2c_set_clientdata(&state->client, state);
> + + i2c_set_clientdata(client, state);
>
> The call to i2c_attach_client is no longer needed, if the probe
> routine exits successfully, then the driver will be automatically
> -attached by the core. Change the probe routine as so:
> +attached by the core. Change the probe routine as so::
>
> -- ret = i2c_attach_client(&state->i2c_client);
> -- if (ret < 0) {
> -- dev_err(dev, "failed to attach client\n");
> -- kfree(state);
> -- return ret;
> -- }
> + - ret = i2c_attach_client(&state->i2c_client);
> + - if (ret < 0) {
> + - dev_err(dev, "failed to attach client\n");
> + - kfree(state);
> + - return ret;
> + - }
>
>
> Remove the storage of 'struct i2c_client' from the 'struct example_state'
> as we are provided with the i2c_client in our example_probe. Instead we
> store a pointer to it for when it is needed.
>
> -struct example_state {
> -- struct i2c_client client;
> -+ struct i2c_client *client;
> +::
>
> -the new i2c client as so:
> + struct example_state {
> + - struct i2c_client client;
> + + struct i2c_client *client;
>
> -- struct device *dev = &adap->dev; /* to use for dev_ reports */
> -+ struct device *dev = &i2c_client->dev; /* to use for dev_ reports */
> +the new i2c client as so::
> +
> + - struct device *dev = &adap->dev; /* to use for dev_ reports */
> + + struct device *dev = &i2c_client->dev; /* to use for dev_ reports */
>
> And remove the change after our client is attached, as the driver no
> -longer needs to register a new client structure with the core:
> +longer needs to register a new client structure with the core::
>
> -- dev = &state->i2c_client.dev;
> + - dev = &state->i2c_client.dev;
>
> In the probe routine, ensure that the new state has the client stored
> -in it:
> +in it::
>
> -static int example_probe(struct i2c_client *i2c_client,
> + static int example_probe(struct i2c_client *i2c_client,
> const struct i2c_device_id *id)
> -{
> + {
> struct example_state *state;
> struct device *dev = &i2c_client->dev;
> int ret;
> @@ -191,48 +195,50 @@ static int example_probe(struct i2c_client *i2c_client,
> return -ENOMEM;
> }
>
> -+ state->client = i2c_client;
> + + state->client = i2c_client;
>
> Update the detach method, by changing the name to _remove and
> to delete the i2c_detach_client call. It is possible that you
> can also remove the ret variable as it is not needed for any
> of the core functions.
>
> -- static int example_detach(struct i2c_client *client)
> -+ static int example_remove(struct i2c_client *client)
> -{
> +::
> +
> + - static int example_detach(struct i2c_client *client)
> + + static int example_remove(struct i2c_client *client)
> + {
> struct example_state *state = i2c_get_clientdata(client);
>
> -- i2c_detach_client(client);
> + - i2c_detach_client(client);
>
> And finally ensure that we have the correct ID table for the i2c-core
> -and other utilities:
> +and other utilities::
>
> -+ struct i2c_device_id example_idtable[] = {
> -+ { "example", 0 },
> -+ { }
> -+};
> -+
> -+MODULE_DEVICE_TABLE(i2c, example_idtable);
> + + struct i2c_device_id example_idtable[] = {
> + + { "example", 0 },
> + + { }
> + +};
> + +
> + +MODULE_DEVICE_TABLE(i2c, example_idtable);
>
> -static struct i2c_driver example_driver = {
> + static struct i2c_driver example_driver = {
> .driver = {
> .owner = THIS_MODULE,
> .name = "example",
> },
> -+ .id_table = example_ids,
> + + .id_table = example_ids,
>
>
> -Our driver should now look like this:
> +Our driver should now look like this::
>
> -struct example_state {
> + struct example_state {
> struct i2c_client *client;
> ....
> -};
> + };
>
> -static int example_probe(struct i2c_client *client,
> + static int example_probe(struct i2c_client *client,
> const struct i2c_device_id *id)
> -{
> + {
> struct example_state *state;
> struct device *dev = &client->dev;
>
> @@ -250,24 +256,24 @@ static int example_probe(struct i2c_client *client,
> dev_info(dev, "example client created\n");
>
> return 0;
> -}
> + }
>
> -static int example_remove(struct i2c_client *client)
> -{
> + static int example_remove(struct i2c_client *client)
> + {
> struct example_state *state = i2c_get_clientdata(client);
>
> kfree(state);
> return 0;
> -}
> + }
>
> -static struct i2c_device_id example_idtable[] = {
> + static struct i2c_device_id example_idtable[] = {
> { "example", 0 },
> { }
> -};
> + };
>
> -MODULE_DEVICE_TABLE(i2c, example_idtable);
> + MODULE_DEVICE_TABLE(i2c, example_idtable);
>
> -static struct i2c_driver example_driver = {
> + static struct i2c_driver example_driver = {
> .driver = {
> .owner = THIS_MODULE,
> .name = "example",
> @@ -276,4 +282,4 @@ static struct i2c_driver example_driver = {
> .id_table = example_idtable,
> .probe = example_probe,
> .remove = example_remove,
> -};
> + };
> diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients.rst
> similarity index 91%
> rename from Documentation/i2c/writing-clients
> rename to Documentation/i2c/writing-clients.rst
> index a755b141fa4a..dddf0a14ab7c 100644
> --- a/Documentation/i2c/writing-clients
> +++ b/Documentation/i2c/writing-clients.rst
> @@ -1,3 +1,7 @@
> +===================
> +Writing I2C Clients
> +===================
> +
> This is a small guide for those who want to write kernel drivers for I2C
> or SMBus devices, using Linux as the protocol host/master (not slave).
>
> @@ -12,7 +16,7 @@ General remarks
> Try to keep the kernel namespace as clean as possible. The best way to
> do this is to use a unique prefix for all global symbols. This is
> especially important for exported symbols, but it is a good idea to do
> -it for non-exported symbols too. We will use the prefix `foo_' in this
> +it for non-exported symbols too. We will use the prefix ``foo_`` in this
> tutorial.
>
>
> @@ -25,15 +29,17 @@ routines, and should be zero-initialized except for fields with data you
> provide. A client structure holds device-specific information like the
> driver model device node, and its I2C address.
>
> -static struct i2c_device_id foo_idtable[] = {
> +::
> +
> + static struct i2c_device_id foo_idtable[] = {
> { "foo", my_id_for_foo },
> { "bar", my_id_for_bar },
> { }
> -};
> + };
>
> -MODULE_DEVICE_TABLE(i2c, foo_idtable);
> + MODULE_DEVICE_TABLE(i2c, foo_idtable);
>
> -static struct i2c_driver foo_driver = {
> + static struct i2c_driver foo_driver = {
> .driver = {
> .name = "foo",
> .pm = &foo_pm_ops, /* optional */
> @@ -49,7 +55,7 @@ static struct i2c_driver foo_driver = {
>
> .shutdown = foo_shutdown, /* optional */
> .command = foo_command, /* optional, deprecated */
> -}
> + }
>
> The name field is the driver name, and must not contain spaces. It
> should match the module name (if the driver can be compiled as a module),
> @@ -64,16 +70,18 @@ below.
> Extra client data
> =================
>
> -Each client structure has a special `data' field that can point to any
> +Each client structure has a special ``data`` field that can point to any
> structure at all. You should use this to keep device-specific data.
>
> +::
> +
> /* store the value */
> void i2c_set_clientdata(struct i2c_client *client, void *data);
>
> /* retrieve the value */
> void *i2c_get_clientdata(const struct i2c_client *client);
>
> -Note that starting with kernel 2.6.34, you don't have to set the `data' field
> +Note that starting with kernel 2.6.34, you don't have to set the ``data`` field
> to NULL in remove() or if probe() failed anymore. The i2c-core does this
> automatically on these occasions. Those are also the only times the core will
> touch this field.
> @@ -92,25 +100,25 @@ but many chips have some kind of register-value idea that can easily
> be encapsulated.
>
> The below functions are simple examples, and should not be copied
> -literally.
> +literally::
>
> -int foo_read_value(struct i2c_client *client, u8 reg)
> -{
> + int foo_read_value(struct i2c_client *client, u8 reg)
> + {
> if (reg < 0x10) /* byte-sized register */
> return i2c_smbus_read_byte_data(client, reg);
> else /* word-sized register */
> return i2c_smbus_read_word_data(client, reg);
> -}
> + }
>
> -int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
> -{
> + int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
> + {
> if (reg == 0x10) /* Impossible to write - driver error! */
> return -EINVAL;
> else if (reg < 0x10) /* byte-sized register */
> return i2c_smbus_write_byte_data(client, reg, value);
> else /* word-sized register */
> return i2c_smbus_write_word_data(client, reg, value);
> -}
> + }
>
>
> Probing and attaching
> @@ -145,6 +153,8 @@ I2C device drivers using this binding model work just like any other
> kind of driver in Linux: they provide a probe() method to bind to
> those devices, and a remove() method to unbind.
>
> +::
> +
> static int foo_probe(struct i2c_client *client,
> const struct i2c_device_id *id);
> static int foo_remove(struct i2c_client *client);
> @@ -240,37 +250,41 @@ When the kernel is booted, or when your foo driver module is inserted,
> you have to do some initializing. Fortunately, just registering the
> driver module is usually enough.
>
> -static int __init foo_init(void)
> -{
> +::
> +
> + static int __init foo_init(void)
> + {
> return i2c_add_driver(&foo_driver);
> -}
> -module_init(foo_init);
> + }
> + module_init(foo_init);
>
> -static void __exit foo_cleanup(void)
> -{
> + static void __exit foo_cleanup(void)
> + {
> i2c_del_driver(&foo_driver);
> -}
> -module_exit(foo_cleanup);
> + }
> + module_exit(foo_cleanup);
>
> -The module_i2c_driver() macro can be used to reduce above code.
> + The module_i2c_driver() macro can be used to reduce above code.
>
> -module_i2c_driver(foo_driver);
> + module_i2c_driver(foo_driver);
>
> -Note that some functions are marked by `__init'. These functions can
> +Note that some functions are marked by ``__init``. These functions can
> be removed after kernel booting (or module loading) is completed.
> -Likewise, functions marked by `__exit' are dropped by the compiler when
> +Likewise, functions marked by ``__exit`` are dropped by the compiler when
> the code is built into the kernel, as they would never be called.
>
>
> Driver Information
> ==================
>
> -/* Substitute your own name and email address */
> -MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
> -MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
> +::
>
> -/* a few non-GPL license types are also allowed */
> -MODULE_LICENSE("GPL");
> + /* Substitute your own name and email address */
> + MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
> + MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
> +
> + /* a few non-GPL license types are also allowed */
> + MODULE_LICENSE("GPL");
>
>
> Power Management
> @@ -323,6 +337,8 @@ commands, but only some of them understand plain I2C!
> Plain I2C communication
> -----------------------
>
> +::
> +
> int i2c_master_send(struct i2c_client *client, const char *buf,
> int count);
> int i2c_master_recv(struct i2c_client *client, char *buf, int count);
> @@ -334,6 +350,8 @@ to read/write (must be less than the length of the buffer, also should be
> less than 64k since msg.len is u16.) Returned is the actual number of bytes
> read/written.
>
> +::
> +
> int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
> int num);
>
> @@ -343,13 +361,15 @@ stop bit is sent between transaction. The i2c_msg structure contains
> for each message the client address, the number of bytes of the message
> and the message data itself.
>
> -You can read the file `i2c-protocol' for more information about the
> +You can read the file ``i2c-protocol`` for more information about the
> actual I2C protocol.
>
>
> SMBus communication
> -------------------
>
> +::
> +
> s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
> unsigned short flags, char read_write, u8 command,
> int size, union i2c_smbus_data *data);
> @@ -357,6 +377,8 @@ SMBus communication
> This is the generic SMBus function. All functions below are implemented
> in terms of it. Never use this function directly!
>
> +::
> +
> s32 i2c_smbus_read_byte(struct i2c_client *client);
> s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);
> s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);
> @@ -376,7 +398,7 @@ in terms of it. Never use this function directly!
> const u8 *values);
>
> These ones were removed from i2c-core because they had no users, but could
> -be added back later if needed:
> +be added back later if needed::
>
> s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);
> s32 i2c_smbus_process_call(struct i2c_client *client,
> @@ -389,7 +411,7 @@ transactions return 0 on success; the 'read' transactions return the read
> value, except for block transactions, which return the number of values
> read. The block buffers need not be longer than 32 bytes.
>
> -You can read the file `smbus-protocol' for more information about the
> +You can read the file ``smbus-protocol`` for more information about the
> actual SMBus protocol.
>
>
> @@ -397,7 +419,7 @@ General purpose routines
> ========================
>
> Below all general purpose routines are listed, that were not mentioned
> -before.
> +before::
>
> /* Return the adapter number for a specific adapter */
> int i2c_adapter_id(struct i2c_adapter *adap);
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 13c3188f6a68..ded1081e8d5f 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -104,6 +104,7 @@ needed).
> fb/index
> fpga/index
> hid/index
> + i2c/index
> iio/index
> infiniband/index
> leds/index
> diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602
> index a45702865a38..0feffd5af411 100644
> --- a/Documentation/spi/spi-sc18is602
> +++ b/Documentation/spi/spi-sc18is602
> @@ -17,7 +17,7 @@ kernel's SPI core subsystem.
>
> The driver does not probe for supported chips, since the SI18IS602/603 does not
> support Chip ID registers. You will have to instantiate the devices explicitly.
> -Please see Documentation/i2c/instantiating-devices for details.
> +Please see Documentation/i2c/instantiating-devices.rst for details.
>
>
> Usage Notes
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 5d4da1035a03..ce925b6e3bcc 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -666,7 +666,7 @@ ALI1563 I2C DRIVER
> M: Rudolf Marek <r.marek@assembler.cz>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/busses/i2c-ali1563
> +F: Documentation/i2c/busses/i2c-ali1563.rst
> F: drivers/i2c/busses/i2c-ali1563.c
>
> ALLEGRO DVT VIDEO IP CORE DRIVER
> @@ -6657,7 +6657,7 @@ L: linux-i2c@vger.kernel.org
> S: Supported
> F: drivers/i2c/muxes/i2c-mux-gpio.c
> F: include/linux/platform_data/i2c-mux-gpio.h
> -F: Documentation/i2c/muxes/i2c-mux-gpio
> +F: Documentation/i2c/muxes/i2c-mux-gpio.rst
>
> GENERIC HDLC (WAN) DRIVERS
> M: Krzysztof Halasa <khc@pm.waw.pl>
> @@ -7393,14 +7393,14 @@ I2C CONTROLLER DRIVER FOR NVIDIA GPU
> M: Ajay Gupta <ajayg@nvidia.com>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/busses/i2c-nvidia-gpu
> +F: Documentation/i2c/busses/i2c-nvidia-gpu.rst
> F: drivers/i2c/busses/i2c-nvidia-gpu.c
>
> I2C MUXES
> M: Peter Rosin <peda@axentia.se>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/i2c-topology
> +F: Documentation/i2c/i2c-topology.rst
> F: Documentation/i2c/muxes/
> F: Documentation/devicetree/bindings/i2c/i2c-mux*
> F: Documentation/devicetree/bindings/i2c/i2c-arb*
> @@ -7420,8 +7420,8 @@ I2C OVER PARALLEL PORT
> M: Jean Delvare <jdelvare@suse.com>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/busses/i2c-parport
> -F: Documentation/i2c/busses/i2c-parport-light
> +F: Documentation/i2c/busses/i2c-parport.rst
> +F: Documentation/i2c/busses/i2c-parport-light.rst
> F: drivers/i2c/busses/i2c-parport.c
> F: drivers/i2c/busses/i2c-parport-light.c
>
> @@ -7455,7 +7455,7 @@ I2C-TAOS-EVM DRIVER
> M: Jean Delvare <jdelvare@suse.com>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/busses/i2c-taos-evm
> +F: Documentation/i2c/busses/i2c-taos-evm.rst
> F: drivers/i2c/busses/i2c-taos-evm.c
>
> I2C-TINY-USB DRIVER
> @@ -7469,19 +7469,19 @@ I2C/SMBUS CONTROLLER DRIVERS FOR PC
> M: Jean Delvare <jdelvare@suse.com>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/busses/i2c-ali1535
> -F: Documentation/i2c/busses/i2c-ali1563
> -F: Documentation/i2c/busses/i2c-ali15x3
> -F: Documentation/i2c/busses/i2c-amd756
> -F: Documentation/i2c/busses/i2c-amd8111
> -F: Documentation/i2c/busses/i2c-i801
> -F: Documentation/i2c/busses/i2c-nforce2
> -F: Documentation/i2c/busses/i2c-piix4
> -F: Documentation/i2c/busses/i2c-sis5595
> -F: Documentation/i2c/busses/i2c-sis630
> -F: Documentation/i2c/busses/i2c-sis96x
> -F: Documentation/i2c/busses/i2c-via
> -F: Documentation/i2c/busses/i2c-viapro
> +F: Documentation/i2c/busses/i2c-ali1535.rst
> +F: Documentation/i2c/busses/i2c-ali1563.rst
> +F: Documentation/i2c/busses/i2c-ali15x3.rst
> +F: Documentation/i2c/busses/i2c-amd756.rst
> +F: Documentation/i2c/busses/i2c-amd8111.rst
> +F: Documentation/i2c/busses/i2c-i801.rst
> +F: Documentation/i2c/busses/i2c-nforce2.rst
> +F: Documentation/i2c/busses/i2c-piix4.rst
> +F: Documentation/i2c/busses/i2c-sis5595.rst
> +F: Documentation/i2c/busses/i2c-sis630.rst
> +F: Documentation/i2c/busses/i2c-sis96x.rst
> +F: Documentation/i2c/busses/i2c-via.rst
> +F: Documentation/i2c/busses/i2c-viapro.rst
> F: drivers/i2c/busses/i2c-ali1535.c
> F: drivers/i2c/busses/i2c-ali1563.c
> F: drivers/i2c/busses/i2c-ali15x3.c
> @@ -7510,7 +7510,7 @@ M: Seth Heasley <seth.heasley@intel.com>
> M: Neil Horman <nhorman@tuxdriver.com>
> L: linux-i2c@vger.kernel.org
> F: drivers/i2c/busses/i2c-ismt.c
> -F: Documentation/i2c/busses/i2c-ismt
> +F: Documentation/i2c/busses/i2c-ismt.rst
>
> I2C/SMBUS STUB DRIVER
> M: Jean Delvare <jdelvare@suse.com>
> @@ -10236,7 +10236,7 @@ L: linux-i2c@vger.kernel.org
> S: Supported
> F: drivers/i2c/busses/i2c-mlxcpld.c
> F: drivers/i2c/muxes/i2c-mux-mlxcpld.c
> -F: Documentation/i2c/busses/i2c-mlxcpld
> +F: Documentation/i2c/busses/i2c-mlxcpld.rst
>
> MELLANOX MLXCPLD LED DRIVER
> M: Vadim Pasternak <vadimp@mellanox.com>
> @@ -11857,7 +11857,7 @@ M: Andrew Lunn <andrew@lunn.ch>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> F: Documentation/devicetree/bindings/i2c/i2c-ocores.txt
> -F: Documentation/i2c/busses/i2c-ocores
> +F: Documentation/i2c/busses/i2c-ocores.rst
> F: drivers/i2c/busses/i2c-ocores.c
> F: include/linux/platform_data/i2c-ocores.h
>
> @@ -14141,7 +14141,7 @@ F: net/sctp/
> SCx200 CPU SUPPORT
> M: Jim Cromie <jim.cromie@gmail.com>
> S: Odd Fixes
> -F: Documentation/i2c/busses/scx200_acb
> +F: Documentation/i2c/busses/scx200_acb.rst
> F: arch/x86/platform/scx200/
> F: drivers/watchdog/scx200_wdt.c
> F: drivers/i2c/busses/scx200*
> diff --git a/Next/merge.log b/Next/merge.log
> index e9f5123f59ca..b45b3201b1d6 100644
> --- a/Next/merge.log
> +++ b/Next/merge.log
> @@ -2954,7 +2954,7 @@ $ git diff -M --stat --summary HEAD^..
> Documentation/devicetree/bindings/i2c/i2c-omap.txt | 1 +
> .../devicetree/bindings/i2c/i2c-sun6i-p2wi.txt | 41 ---
> .../bindings/i2c/marvell,mv64xxx-i2c.yaml | 124 +++++++
> - Documentation/i2c/busses/i2c-i801 | 3 +-
> + Documentation/i2c/busses/i2c-i801.rst | 3 +-
> MAINTAINERS | 7 +
> arch/arm/include/asm/hardware/iop3xx.h | 2 +
> arch/arm/mach-iop32x/em7210.c | 3 +
> @@ -3251,8 +3251,8 @@ $ git diff -M --stat --summary HEAD^..
> Documentation/fpga/index.rst | 17 +
> Documentation/gpu/msm-crash-dump.rst | 2 +
> Documentation/hid/hid-transport.txt | 6 +-
> - Documentation/i2c/instantiating-devices | 4 +-
> - Documentation/i2c/upgrading-clients | 4 +-
> + Documentation/i2c/instantiating-devices.rst | 4 +-
> + Documentation/i2c/upgrading-clients.rst | 4 +-
> Documentation/ide/changelogs.rst | 17 +
> Documentation/ide/{ide-tape.txt => ide-tape.rst} | 23 +-
> Documentation/ide/{ide.txt => ide.rst} | 147 +-
> diff --git a/drivers/hwmon/atxp1.c b/drivers/hwmon/atxp1.c
> index e232fa948833..79b8df258371 100644
> --- a/drivers/hwmon/atxp1.c
> +++ b/drivers/hwmon/atxp1.c
> @@ -5,7 +5,7 @@
> *
> * The ATXP1 can reside on I2C addresses 0x37 or 0x4e. The chip is
> * not auto-detected by the driver and must be instantiated explicitly.
> - * See Documentation/i2c/instantiating-devices for more information.
> + * See Documentation/i2c/instantiating-devices.rst for more information.
> */
>
> #include <linux/kernel.h>
> diff --git a/drivers/hwmon/smm665.c b/drivers/hwmon/smm665.c
> index d8c91c2cb8cf..9ae0dc28b9cf 100644
> --- a/drivers/hwmon/smm665.c
> +++ b/drivers/hwmon/smm665.c
> @@ -197,7 +197,7 @@ static int smm665_read_adc(struct smm665_data *data, int adc)
> if (rv != -ENXIO) {
> /*
> * We expect ENXIO to reflect NACK
> - * (per Documentation/i2c/fault-codes).
> + * (per Documentation/i2c/fault-codes.rst).
> * Everything else is an error.
> */
> dev_dbg(&client->dev,
> diff --git a/drivers/i2c/Kconfig b/drivers/i2c/Kconfig
> index abedd55a1264..1474e57ecafc 100644
> --- a/drivers/i2c/Kconfig
> +++ b/drivers/i2c/Kconfig
> @@ -54,7 +54,7 @@ config I2C_CHARDEV
> Say Y here to use i2c-* device files, usually found in the /dev
> directory on your system. They make it possible to have user-space
> programs use the I2C bus. Information on how to do this is
> - contained in the file <file:Documentation/i2c/dev-interface>.
> + contained in the file <file:Documentation/i2c/dev-interface.rst>.
>
> This support is also available as a module. If so, the module
> will be called i2c-dev.
> @@ -107,7 +107,7 @@ config I2C_STUB
> especially for certain kinds of sensor chips.
>
> If you do build this module, be sure to read the notes and warnings
> - in <file:Documentation/i2c/i2c-stub>.
> + in <file:Documentation/i2c/i2c-stub.rst>.
>
> If you don't know what to do here, definitely say N.
>
> diff --git a/drivers/i2c/busses/Kconfig b/drivers/i2c/busses/Kconfig
> index 68b677be1fa4..e4be46644e8b 100644
> --- a/drivers/i2c/busses/Kconfig
> +++ b/drivers/i2c/busses/Kconfig
> @@ -1205,7 +1205,7 @@ config I2C_PARPORT
> and makes it easier to add support for new devices.
>
> An adapter type parameter is now mandatory. Please read the file
> - Documentation/i2c/busses/i2c-parport for details.
> + Documentation/i2c/busses/i2c-parport.rst for details.
>
> Another driver exists, named i2c-parport-light, which doesn't depend
> on the parport driver. This is meant for embedded systems. Don't say
> diff --git a/drivers/i2c/busses/i2c-i801.c b/drivers/i2c/busses/i2c-i801.c
> index 1e7f6ae62b4c..a215b336bf5c 100644
> --- a/drivers/i2c/busses/i2c-i801.c
> +++ b/drivers/i2c/busses/i2c-i801.c
> @@ -76,7 +76,7 @@
> * SMBus Host Notify yes
> * Interrupt processing yes
> *
> - * See the file Documentation/i2c/busses/i2c-i801 for details.
> + * See the file Documentation/i2c/busses/i2c-i801.rst for details.
> */
>
> #include <linux/interrupt.h>
> diff --git a/drivers/i2c/busses/i2c-taos-evm.c b/drivers/i2c/busses/i2c-taos-evm.c
> index c82e78f57386..37347c93e8e0 100644
> --- a/drivers/i2c/busses/i2c-taos-evm.c
> +++ b/drivers/i2c/busses/i2c-taos-evm.c
> @@ -125,7 +125,7 @@ static int taos_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
> /*
> * Voluntarily dropping error code of kstrtou8 since all
> * error code that it could return are invalid according
> - * to Documentation/i2c/fault-codes.
> + * to Documentation/i2c/fault-codes.rst.
> */
> if (kstrtou8(p + 1, 16, &data->byte))
> return -EPROTO;
> diff --git a/drivers/i2c/i2c-core-base.c b/drivers/i2c/i2c-core-base.c
> index e77bab2fb467..56b42558575e 100644
> --- a/drivers/i2c/i2c-core-base.c
> +++ b/drivers/i2c/i2c-core-base.c
> @@ -2205,7 +2205,7 @@ static int i2c_detect_address(struct i2c_client *temp_client,
> dev_warn(&adapter->dev,
> "This adapter will soon drop class based instantiation of devices. "
> "Please make sure client 0x%02x gets instantiated by other means. "
> - "Check 'Documentation/i2c/instantiating-devices' for details.\n",
> + "Check 'Documentation/i2c/instantiating-devices.rst' for details.\n",
> info.addr);
>
> dev_dbg(&adapter->dev, "Creating %s at 0x%02x\n",
> @@ -2235,7 +2235,7 @@ static int i2c_detect(struct i2c_adapter *adapter, struct i2c_driver *driver)
> if (adapter->class == I2C_CLASS_DEPRECATED) {
> dev_dbg(&adapter->dev,
> "This adapter dropped support for I2C classes and won't auto-detect %s devices anymore. "
> - "If you need it, check 'Documentation/i2c/instantiating-devices' for alternatives.\n",
> + "If you need it, check 'Documentation/i2c/instantiating-devices.rst' for alternatives.\n",
> driver->driver.name);
> return 0;
> }
> diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
> index 8f99c005458a..d28974ad9e0e 100644
> --- a/drivers/iio/dummy/iio_simple_dummy.c
> +++ b/drivers/iio/dummy/iio_simple_dummy.c
> @@ -693,7 +693,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
> * Varies depending on bus type of the device. As there is no device
> * here, call probe directly. For information on device registration
> * i2c:
> - * Documentation/i2c/writing-clients
> + * Documentation/i2c/writing-clients.rst
> * spi:
> * Documentation/spi/spi-summary
> */
> diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
> index 225a8df1d4e9..1803f3cab39f 100644
> --- a/drivers/rtc/rtc-ds1374.c
> +++ b/drivers/rtc/rtc-ds1374.c
> @@ -14,7 +14,7 @@
> */
> /*
> * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
> - * recommened in .../Documentation/i2c/writing-clients section
> + * recommened in .../Documentation/i2c/writing-clients.rst section
> * "Sending and receiving", using SMBus level communication is preferred.
> */
>
> diff --git a/include/linux/i2c.h b/include/linux/i2c.h
> index fa5552c2307b..c0a78c069117 100644
> --- a/include/linux/i2c.h
> +++ b/include/linux/i2c.h
> @@ -521,7 +521,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
> *
> * The return codes from the @master_xfer{_atomic} fields should indicate the
> * type of error code that occurred during the transfer, as documented in the
> - * Kernel Documentation file Documentation/i2c/fault-codes.
> + * Kernel Documentation file Documentation/i2c/fault-codes.rst.
> */
> struct i2c_algorithm {
> /*
> --
> 2.21.0
>
--
Alexandre Belloni, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
2019-06-28 21:23 ` [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset Mauro Carvalho Chehab
` (2 preceding siblings ...)
2019-06-29 11:37 ` Alexandre Belloni
@ 2019-07-14 16:23 ` Jonathan Cameron
3 siblings, 0 replies; 14+ messages in thread
From: Jonathan Cameron @ 2019-07-14 16:23 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Hartmut Knaack, Lars-Peter Clausen,
Peter Meerwald-Stadler, Alessandro Zummo, Alexandre Belloni,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
On Fri, 28 Jun 2019 18:23:14 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Convert each file at I2C subsystem, renaming them to .rst and
> adding to the driver-api book.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
For the minimal touch on iio,
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Jonathan
> ---
> Documentation/IPMB.txt | 2 +-
> .../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +-
> Documentation/hwmon/adm1021.rst | 2 +-
> Documentation/hwmon/adm1275.rst | 2 +-
> Documentation/hwmon/hih6130.rst | 2 +-
> Documentation/hwmon/ibm-cffps.rst | 2 +-
> Documentation/hwmon/lm25066.rst | 2 +-
> Documentation/hwmon/max16064.rst | 2 +-
> Documentation/hwmon/max16065.rst | 2 +-
> Documentation/hwmon/max20751.rst | 2 +-
> Documentation/hwmon/max34440.rst | 2 +-
> Documentation/hwmon/max6650.rst | 2 +-
> Documentation/hwmon/max8688.rst | 2 +-
> Documentation/hwmon/menf21bmc.rst | 2 +-
> Documentation/hwmon/pcf8591.rst | 2 +-
> Documentation/hwmon/sht3x.rst | 2 +-
> Documentation/hwmon/shtc1.rst | 2 +-
> Documentation/hwmon/tmp103.rst | 2 +-
> Documentation/hwmon/tps40422.rst | 2 +-
> Documentation/hwmon/ucd9000.rst | 2 +-
> Documentation/hwmon/ucd9200.rst | 2 +-
> Documentation/hwmon/via686a.rst | 2 +-
> Documentation/hwmon/zl6100.rst | 2 +-
> .../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +-
> .../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 +
> .../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 63 +++---
> Documentation/i2c/busses/i2c-amd-mp2 | 23 ---
> Documentation/i2c/busses/i2c-amd-mp2.rst | 25 +++
> .../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +-
> .../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +-
> .../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 +
> .../i2c/busses/{i2c-i801 => i2c-i801.rst} | 31 ++-
> .../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +-
> .../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 +
> .../busses/{i2c-nforce2 => i2c-nforce2.rst} | 23 ++-
> .../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +-
> .../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +-
> Documentation/i2c/busses/i2c-parport | 178 ----------------
> ...2c-parport-light => i2c-parport-light.rst} | 2 +
> Documentation/i2c/busses/i2c-parport.rst | 190 +++++++++++++++++
> .../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +-
> .../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 14 +-
> .../busses/{i2c-sis5595 => i2c-sis5595.rst} | 18 +-
> Documentation/i2c/busses/i2c-sis630 | 58 ------
> Documentation/i2c/busses/i2c-sis630.rst | 64 ++++++
> .../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 28 ++-
> .../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +-
> .../i2c/busses/{i2c-via => i2c-via.rst} | 20 +-
> .../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +-
> Documentation/i2c/busses/index.rst | 33 +++
> .../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +-
> .../i2c/{dev-interface => dev-interface.rst} | 94 +++++----
> ...-considerations => dma-considerations.rst} | 0
> .../i2c/{fault-codes => fault-codes.rst} | 4 +
> .../i2c/{functionality => functionality.rst} | 18 +-
> ...ult-injection => gpio-fault-injection.rst} | 12 +-
> .../i2c/{i2c-protocol => i2c-protocol.rst} | 28 ++-
> Documentation/i2c/{i2c-stub => i2c-stub.rst} | 19 +-
> .../i2c/{i2c-topology => i2c-topology.rst} | 68 +++---
> Documentation/i2c/index.rst | 38 ++++
> ...ting-devices => instantiating-devices.rst} | 45 ++--
> .../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +--
> ...e-parameters => old-module-parameters.rst} | 27 ++-
> ...eprom-backend => slave-eeprom-backend.rst} | 3 +-
> .../{slave-interface => slave-interface.rst} | 32 +--
> .../{smbus-protocol => smbus-protocol.rst} | 74 ++++---
> Documentation/i2c/{summary => summary.rst} | 4 +-
> ...en-bit-addresses => ten-bit-addresses.rst} | 5 +
> ...pgrading-clients => upgrading-clients.rst} | 194 +++++++++---------
> .../{writing-clients => writing-clients.rst} | 94 +++++----
> Documentation/index.rst | 1 +
> Documentation/spi/spi-sc18is602 | 2 +-
> MAINTAINERS | 48 ++---
> Next/merge.log | 6 +-
> drivers/hwmon/atxp1.c | 2 +-
> drivers/hwmon/smm665.c | 2 +-
> drivers/i2c/Kconfig | 4 +-
> drivers/i2c/busses/Kconfig | 2 +-
> drivers/i2c/busses/i2c-i801.c | 2 +-
> drivers/i2c/busses/i2c-taos-evm.c | 2 +-
> drivers/i2c/i2c-core-base.c | 4 +-
> drivers/iio/dummy/iio_simple_dummy.c | 2 +-
> drivers/rtc/rtc-ds1374.c | 2 +-
> include/linux/i2c.h | 2 +-
> 84 files changed, 1065 insertions(+), 750 deletions(-)
> rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
> rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
> rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
> delete mode 100644 Documentation/i2c/busses/i2c-amd-mp2
> create mode 100644 Documentation/i2c/busses/i2c-amd-mp2.rst
> rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
> rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
> rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
> rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
> rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
> rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
> rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (68%)
> rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
> rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
> delete mode 100644 Documentation/i2c/busses/i2c-parport
> rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (92%)
> create mode 100644 Documentation/i2c/busses/i2c-parport.rst
> rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
> rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
> rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
> delete mode 100644 Documentation/i2c/busses/i2c-sis630
> create mode 100644 Documentation/i2c/busses/i2c-sis630.rst
> rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (75%)
> rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
> rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (61%)
> rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
> create mode 100644 Documentation/i2c/busses/index.rst
> rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
> rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
> rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
> rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
> rename Documentation/i2c/{functionality => functionality.rst} (91%)
> rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
> rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
> rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
> rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
> create mode 100644 Documentation/i2c/index.rst
> rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
> rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
> rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
> rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
> rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
> rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (84%)
> rename Documentation/i2c/{summary => summary.rst} (96%)
> rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
> rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (56%)
> rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
>
> diff --git a/Documentation/IPMB.txt b/Documentation/IPMB.txt
> index a6ed8b68bd0f..cd20c9764705 100644
> --- a/Documentation/IPMB.txt
> +++ b/Documentation/IPMB.txt
> @@ -82,7 +82,7 @@ Instantiate the device
> ----------------------
>
> After loading the driver, you can instantiate the device as
> -described in 'Documentation/i2c/instantiating-devices'.
> +described in 'Documentation/i2c/instantiating-devices.rst'.
> If you have multiple BMCs, each connected to your Satellite MC via
> a different I2C bus, you can instantiate a device for each of
> those BMCs.
> diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
> index 2907dab56298..8b444b94e92f 100644
> --- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
> +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
> @@ -42,7 +42,7 @@ Optional properties:
> This means that no unrelated I2C transactions are allowed on the parent I2C
> adapter for the complete multiplexed I2C transaction.
> The properties of mux-locked and parent-locked multiplexers are discussed
> - in more detail in Documentation/i2c/i2c-topology.
> + in more detail in Documentation/i2c/i2c-topology.rst.
>
> For each i2c child node, an I2C child bus will be created. They will
> be numbered based on their order in the device tree.
> diff --git a/Documentation/hwmon/adm1021.rst b/Documentation/hwmon/adm1021.rst
> index 6cbb0f75fe00..116fb2019956 100644
> --- a/Documentation/hwmon/adm1021.rst
> +++ b/Documentation/hwmon/adm1021.rst
> @@ -142,7 +142,7 @@ loading the adm1021 module, then things are good.
> If nothing happens when loading the adm1021 module, and you are certain
> that your specific Xeon processor model includes compatible sensors, you
> will have to explicitly instantiate the sensor chips from user-space. See
> -method 4 in Documentation/i2c/instantiating-devices. Possible slave
> +method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave
> addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that
> only temp2 will be correct and temp1 will have to be ignored.
>
> diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst
> index 9a1913e5b4d9..49966ed70ec6 100644
> --- a/Documentation/hwmon/adm1275.rst
> +++ b/Documentation/hwmon/adm1275.rst
> @@ -75,7 +75,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> The ADM1075, unlike many other PMBus devices, does not support internal voltage
> diff --git a/Documentation/hwmon/hih6130.rst b/Documentation/hwmon/hih6130.rst
> index 649bd4be4fc2..e95d373eb693 100644
> --- a/Documentation/hwmon/hih6130.rst
> +++ b/Documentation/hwmon/hih6130.rst
> @@ -27,7 +27,7 @@ The devices communicate with the I2C protocol. All sensors are set to the same
> I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27)
> can be used in the board setup code.
>
> -Please see Documentation/i2c/instantiating-devices for details on how to
> +Please see Documentation/i2c/instantiating-devices.rst for details on how to
> instantiate I2C devices.
>
> sysfs-Interface
> diff --git a/Documentation/hwmon/ibm-cffps.rst b/Documentation/hwmon/ibm-cffps.rst
> index 52e74e39463a..ef8f3f806968 100644
> --- a/Documentation/hwmon/ibm-cffps.rst
> +++ b/Documentation/hwmon/ibm-cffps.rst
> @@ -17,7 +17,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> Sysfs entries
> diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst
> index da15e3094c8c..30e6e77fb3c8 100644
> --- a/Documentation/hwmon/lm25066.rst
> +++ b/Documentation/hwmon/lm25066.rst
> @@ -76,7 +76,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/max16064.rst b/Documentation/hwmon/max16064.rst
> index 6d5e9538991f..c06249292557 100644
> --- a/Documentation/hwmon/max16064.rst
> +++ b/Documentation/hwmon/max16064.rst
> @@ -28,7 +28,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/max16065.rst b/Documentation/hwmon/max16065.rst
> index fa5c852a178c..45f69f334f25 100644
> --- a/Documentation/hwmon/max16065.rst
> +++ b/Documentation/hwmon/max16065.rst
> @@ -79,7 +79,7 @@ Usage Notes
>
> This driver does not probe for devices, since there is no register which
> can be safely used to identify the chip. You will have to instantiate
> -the devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> WARNING: Do not access chip registers using the i2cdump command, and do not use
> diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst
> index aa4469be6674..fe701e07eaf5 100644
> --- a/Documentation/hwmon/max20751.rst
> +++ b/Documentation/hwmon/max20751.rst
> @@ -30,7 +30,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst
> index 939138e12b02..5744df100a5d 100644
> --- a/Documentation/hwmon/max34440.rst
> +++ b/Documentation/hwmon/max34440.rst
> @@ -83,7 +83,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> For MAX34446, the value of the currX_crit attribute determines if current or
> diff --git a/Documentation/hwmon/max6650.rst b/Documentation/hwmon/max6650.rst
> index 253482add082..7952b6ecaa2d 100644
> --- a/Documentation/hwmon/max6650.rst
> +++ b/Documentation/hwmon/max6650.rst
> @@ -55,7 +55,7 @@ Usage notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> Module parameters
> diff --git a/Documentation/hwmon/max8688.rst b/Documentation/hwmon/max8688.rst
> index 009487759c61..71e7f2cbe2e2 100644
> --- a/Documentation/hwmon/max8688.rst
> +++ b/Documentation/hwmon/max8688.rst
> @@ -28,7 +28,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/menf21bmc.rst b/Documentation/hwmon/menf21bmc.rst
> index 1f0c6b2235ab..978691d5956d 100644
> --- a/Documentation/hwmon/menf21bmc.rst
> +++ b/Documentation/hwmon/menf21bmc.rst
> @@ -28,7 +28,7 @@ Usage Notes
> This driver is part of the MFD driver named "menf21bmc" and does
> not auto-detect devices.
> You will have to instantiate the MFD driver explicitly.
> -Please see Documentation/i2c/instantiating-devices for
> +Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> Sysfs entries
> diff --git a/Documentation/hwmon/pcf8591.rst b/Documentation/hwmon/pcf8591.rst
> index e98bd542a441..5c4e85f53177 100644
> --- a/Documentation/hwmon/pcf8591.rst
> +++ b/Documentation/hwmon/pcf8591.rst
> @@ -68,7 +68,7 @@ Accessing PCF8591 via /sys interface
> The PCF8591 is plainly impossible to detect! Thus the driver won't even
> try. You have to explicitly instantiate the device at the relevant
> address (in the interval [0x48..0x4f]) either through platform data, or
> -using the sysfs interface. See Documentation/i2c/instantiating-devices
> +using the sysfs interface. See Documentation/i2c/instantiating-devices.rst
> for details.
>
> Directories are being created for each instantiated PCF8591:
> diff --git a/Documentation/hwmon/sht3x.rst b/Documentation/hwmon/sht3x.rst
> index 978a7117e4b2..95a850d5b2c1 100644
> --- a/Documentation/hwmon/sht3x.rst
> +++ b/Documentation/hwmon/sht3x.rst
> @@ -26,7 +26,7 @@ scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500.
>
> The device communicates with the I2C protocol. Sensors can have the I2C
> addresses 0x44 or 0x45, depending on the wiring. See
> -Documentation/i2c/instantiating-devices for methods to instantiate the device.
> +Documentation/i2c/instantiating-devices.rst for methods to instantiate the device.
>
> There are two options configurable by means of sht3x_platform_data:
>
> diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst
> index aa116332ba26..70c1192bbd8c 100644
> --- a/Documentation/hwmon/shtc1.rst
> +++ b/Documentation/hwmon/shtc1.rst
> @@ -36,7 +36,7 @@ humidity is expressed as a percentage. Driver can be used as well for SHTW1
> chip, which has the same electrical interface.
>
> The device communicates with the I2C protocol. All sensors are set to I2C
> -address 0x70. See Documentation/i2c/instantiating-devices for methods to
> +address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to
> instantiate the device.
>
> There are two options configurable by means of shtc1_platform_data:
> diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst
> index 15d25806d585..205de6148fcb 100644
> --- a/Documentation/hwmon/tmp103.rst
> +++ b/Documentation/hwmon/tmp103.rst
> @@ -30,4 +30,4 @@ The driver provides the common sysfs-interface for temperatures (see
> Documentation/hwmon/sysfs-interface.rst under Temperatures).
>
> Please refer how to instantiate this driver:
> -Documentation/i2c/instantiating-devices
> +Documentation/i2c/instantiating-devices.rst
> diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst
> index b691e30479dd..8fe3e1c3572e 100644
> --- a/Documentation/hwmon/tps40422.rst
> +++ b/Documentation/hwmon/tps40422.rst
> @@ -28,7 +28,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/ucd9000.rst b/Documentation/hwmon/ucd9000.rst
> index ebc4f2b3bfea..746f21fcb48c 100644
> --- a/Documentation/hwmon/ucd9000.rst
> +++ b/Documentation/hwmon/ucd9000.rst
> @@ -64,7 +64,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/ucd9200.rst b/Documentation/hwmon/ucd9200.rst
> index b819dfd75f71..4f0e7c3ca6f4 100644
> --- a/Documentation/hwmon/ucd9200.rst
> +++ b/Documentation/hwmon/ucd9200.rst
> @@ -40,7 +40,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
>
> diff --git a/Documentation/hwmon/via686a.rst b/Documentation/hwmon/via686a.rst
> index a343c35df740..7ab9ddebcf79 100644
> --- a/Documentation/hwmon/via686a.rst
> +++ b/Documentation/hwmon/via686a.rst
> @@ -40,7 +40,7 @@ all as a 686A.
>
> The Via 686a southbridge has integrated hardware monitor functionality.
> It also has an I2C bus, but this driver only supports the hardware monitor.
> -For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro>
> +For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro.rst>
>
> The Via 686a implements three temperature sensors, two fan rotation speed
> sensors, five voltage sensors and alarms.
> diff --git a/Documentation/hwmon/zl6100.rst b/Documentation/hwmon/zl6100.rst
> index 41513bb7fe51..968aff10ce0a 100644
> --- a/Documentation/hwmon/zl6100.rst
> +++ b/Documentation/hwmon/zl6100.rst
> @@ -121,7 +121,7 @@ Usage Notes
> -----------
>
> This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see Documentation/i2c/instantiating-devices for
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
> details.
>
> .. warning::
> diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535.rst
> similarity index 82%
> rename from Documentation/i2c/busses/i2c-ali1535
> rename to Documentation/i2c/busses/i2c-ali1535.rst
> index 5d46342e486a..6941064730dc 100644
> --- a/Documentation/i2c/busses/i2c-ali1535
> +++ b/Documentation/i2c/busses/i2c-ali1535.rst
> @@ -1,16 +1,19 @@
> +=========================
> Kernel driver i2c-ali1535
> +=========================
>
> Supported adapters:
> * Acer Labs, Inc. ALI 1535 (south bridge)
> +
> Datasheet: Now under NDA
> http://www.ali.com.tw/
>
> Authors:
> - Frodo Looijaard <frodol@dds.nl>,
> - Philip Edelbrock <phil@netroedge.com>,
> - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> - Dan Eaton <dan.eaton@rocketlogix.com>,
> - Stephen Rousset<stephen.rousset@rocketlogix.com>
> + - Frodo Looijaard <frodol@dds.nl>,
> + - Philip Edelbrock <phil@netroedge.com>,
> + - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> + - Dan Eaton <dan.eaton@rocketlogix.com>,
> + - Stephen Rousset<stephen.rousset@rocketlogix.com>
>
> Description
> -----------
> diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563.rst
> similarity index 93%
> rename from Documentation/i2c/busses/i2c-ali1563
> rename to Documentation/i2c/busses/i2c-ali1563.rst
> index 41b1a077e4c7..eec32c3ba92a 100644
> --- a/Documentation/i2c/busses/i2c-ali1563
> +++ b/Documentation/i2c/busses/i2c-ali1563.rst
> @@ -1,7 +1,10 @@
> +=========================
> Kernel driver i2c-ali1563
> +=========================
>
> Supported adapters:
> * Acer Labs, Inc. ALI 1563 (south bridge)
> +
> Datasheet: Now under NDA
> http://www.ali.com.tw/
>
> diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3.rst
> similarity index 72%
> rename from Documentation/i2c/busses/i2c-ali15x3
> rename to Documentation/i2c/busses/i2c-ali15x3.rst
> index 42888d8ac124..c70f7c66db51 100644
> --- a/Documentation/i2c/busses/i2c-ali15x3
> +++ b/Documentation/i2c/busses/i2c-ali15x3.rst
> @@ -1,20 +1,23 @@
> +=========================
> Kernel driver i2c-ali15x3
> +=========================
>
> Supported adapters:
> * Acer Labs, Inc. ALI 1533 and 1543C (south bridge)
> +
> Datasheet: Now under NDA
> http://www.ali.com.tw/
>
> Authors:
> - Frodo Looijaard <frodol@dds.nl>,
> - Philip Edelbrock <phil@netroedge.com>,
> - Mark D. Studebaker <mdsxyz123@yahoo.com>
> + - Frodo Looijaard <frodol@dds.nl>,
> + - Philip Edelbrock <phil@netroedge.com>,
> + - Mark D. Studebaker <mdsxyz123@yahoo.com>
>
> Module Parameters
> -----------------
>
> * force_addr: int
> - Initialize the base address of the i2c controller
> + Initialize the base address of the i2c controller
>
>
> Notes
> @@ -25,7 +28,9 @@ the BIOS. Does not do a PCI force; the device must still be present in
> lspci. Don't use this unless the driver complains that the base address is
> not set.
>
> -Example: 'modprobe i2c-ali15x3 force_addr=0xe800'
> +Example::
> +
> + modprobe i2c-ali15x3 force_addr=0xe800
>
> SMBus periodically hangs on ASUS P5A motherboards and can only be cleared
> by a power cycle. Cause unknown (see Issues below).
> @@ -38,47 +43,53 @@ This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
> M1541 and M1543C South Bridges.
>
> The M1543C is a South bridge for desktop systems.
> +
> The M1541 is a South bridge for portable systems.
> +
> They are part of the following ALI chipsets:
>
> * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and
> - 100MHz CPU Front Side bus
> + 100MHz CPU Front Side bus
> * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz
> - CPU Front Side bus
> + CPU Front Side bus
> +
> Some Aladdin V motherboards:
> - Asus P5A
> - Atrend ATC-5220
> - BCM/GVC VP1541
> - Biostar M5ALA
> - Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't
> - enable the 7101 device! **)
> - Iwill XA100 Plus
> - Micronics C200
> - Microstar (MSI) MS-5169
> + - Asus P5A
> + - Atrend ATC-5220
> + - BCM/GVC VP1541
> + - Biostar M5ALA
> + - Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't
> + enable the 7101 device!)
> + - Iwill XA100 Plus
> + - Micronics C200
> + - Microstar (MSI) MS-5169
>
> * "Aladdin IV" includes the M1541 Socket 7 North bridge
> - with host bus up to 83.3 MHz.
> + with host bus up to 83.3 MHz.
>
> For an overview of these chips see http://www.acerlabs.com. At this time the
> full data sheets on the web site are password protected, however if you
> contact the ALI office in San Jose they may give you the password.
>
> The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An
> -output of lspci will show something similar to the following:
> +output of lspci will show something similar to the following::
>
> 00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03)
> 00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED
> 00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3)
> 00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1)
>
> -** IMPORTANT **
> -** If you have a M1533 or M1543C on the board and you get
> -** "ali15x3: Error: Can't detect ali15x3!"
> -** then run lspci.
> -** If you see the 1533 and 5229 devices but NOT the 7101 device,
> -** then you must enable ACPI, the PMU, SMB, or something similar
> -** in the BIOS.
> -** The driver won't work if it can't find the M7101 device.
> +.. important::
> +
> + If you have a M1533 or M1543C on the board and you get
> + "ali15x3: Error: Can't detect ali15x3!"
> + then run lspci.
> +
> + If you see the 1533 and 5229 devices but NOT the 7101 device,
> + then you must enable ACPI, the PMU, SMB, or something similar
> + in the BIOS.
> +
> + The driver won't work if it can't find the M7101 device.
>
> The SMB controller is part of the M7101 device, which is an ACPI-compliant
> Power Management Unit (PMU).
> diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2
> deleted file mode 100644
> index 6571487171f4..000000000000
> --- a/Documentation/i2c/busses/i2c-amd-mp2
> +++ /dev/null
> @@ -1,23 +0,0 @@
> -Kernel driver i2c-amd-mp2
> -
> -Supported adapters:
> - * AMD MP2 PCIe interface
> -
> -Datasheet: not publicly available.
> -
> -Authors:
> - Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
> - Nehal Shah <nehal-bakulchandra.shah@amd.com>
> - Elie Morisse <syniurge@gmail.com>
> -
> -Description
> ------------
> -
> -The MP2 is an ARM processor programmed as an I2C controller and communicating
> -with the x86 host through PCI.
> -
> -If you see something like this:
> -
> -03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
> -
> -in your 'lspci -v', then this driver is for your device.
> diff --git a/Documentation/i2c/busses/i2c-amd-mp2.rst b/Documentation/i2c/busses/i2c-amd-mp2.rst
> new file mode 100644
> index 000000000000..ebc2fa899325
> --- /dev/null
> +++ b/Documentation/i2c/busses/i2c-amd-mp2.rst
> @@ -0,0 +1,25 @@
> +=========================
> +Kernel driver i2c-amd-mp2
> +=========================
> +
> +Supported adapters:
> + * AMD MP2 PCIe interface
> +
> +Datasheet: not publicly available.
> +
> +Authors:
> + - Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
> + - Nehal Shah <nehal-bakulchandra.shah@amd.com>
> + - Elie Morisse <syniurge@gmail.com>
> +
> +Description
> +-----------
> +
> +The MP2 is an ARM processor programmed as an I2C controller and communicating
> +with the x86 host through PCI.
> +
> +If you see something like this::
> +
> + 03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
> +
> +in your ``lspci -v``, then this driver is for your device.
> diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756.rst
> similarity index 79%
> rename from Documentation/i2c/busses/i2c-amd756
> rename to Documentation/i2c/busses/i2c-amd756.rst
> index 67f30874d0bf..bc93f392a4fc 100644
> --- a/Documentation/i2c/busses/i2c-amd756
> +++ b/Documentation/i2c/busses/i2c-amd756.rst
> @@ -1,18 +1,22 @@
> +========================
> Kernel driver i2c-amd756
> +========================
>
> Supported adapters:
> * AMD 756
> * AMD 766
> * AMD 768
> * AMD 8111
> +
> Datasheets: Publicly available on AMD website
>
> * nVidia nForce
> +
> Datasheet: Unavailable
>
> Authors:
> - Frodo Looijaard <frodol@dds.nl>,
> - Philip Edelbrock <phil@netroedge.com>
> + - Frodo Looijaard <frodol@dds.nl>,
> + - Philip Edelbrock <phil@netroedge.com>
>
> Description
> -----------
> diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111.rst
> similarity index 66%
> rename from Documentation/i2c/busses/i2c-amd8111
> rename to Documentation/i2c/busses/i2c-amd8111.rst
> index 460dd6635fd2..d08bf0a7f0ac 100644
> --- a/Documentation/i2c/busses/i2c-amd8111
> +++ b/Documentation/i2c/busses/i2c-amd8111.rst
> @@ -1,4 +1,6 @@
> +=========================
> Kernel driver i2c-adm8111
> +=========================
>
> Supported adapters:
> * AMD-8111 SMBus 2.0 PCI interface
> @@ -13,14 +15,14 @@ Author: Vojtech Pavlik <vojtech@suse.cz>
> Description
> -----------
>
> -If you see something like this:
> +If you see something like this::
>
> -00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
> - Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
> - Flags: medium devsel, IRQ 19
> - I/O ports at d400 [size=32]
> + 00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
> + Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
> + Flags: medium devsel, IRQ 19
> + I/O ports at d400 [size=32]
>
> -in your 'lspci -v', then this driver is for your chipset.
> +in your ``lspci -v``, then this driver is for your chipset.
>
> Process Call Support
> --------------------
> diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c.rst
> similarity index 91%
> rename from Documentation/i2c/busses/i2c-diolan-u2c
> rename to Documentation/i2c/busses/i2c-diolan-u2c.rst
> index 0d6018c316c7..c18cbdcdf73c 100644
> --- a/Documentation/i2c/busses/i2c-diolan-u2c
> +++ b/Documentation/i2c/busses/i2c-diolan-u2c.rst
> @@ -1,7 +1,10 @@
> +============================
> Kernel driver i2c-diolan-u2c
> +============================
>
> Supported adapters:
> * Diolan U2C-12 I2C-USB adapter
> +
> Documentation:
> http://www.diolan.com/i2c/u2c12.html
>
> diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801.rst
> similarity index 89%
> rename from Documentation/i2c/busses/i2c-i801
> rename to Documentation/i2c/busses/i2c-i801.rst
> index d247edcb0f99..976b42a15129 100644
> --- a/Documentation/i2c/busses/i2c-i801
> +++ b/Documentation/i2c/busses/i2c-i801.rst
> @@ -1,4 +1,7 @@
> +======================
> Kernel driver i2c-i801
> +======================
> +
>
> Supported adapters:
> * Intel 82801AA and 82801AB (ICH and ICH0 - part of the
> @@ -38,27 +41,32 @@ Supported adapters:
> * Intel Ice Lake (PCH)
> * Intel Comet Lake (PCH)
> * Intel Elkhart Lake (PCH)
> +
> Datasheets: Publicly available at the Intel website
>
> On Intel Patsburg and later chipsets, both the normal host SMBus controller
> and the additional 'Integrated Device Function' controllers are supported.
>
> Authors:
> - Mark Studebaker <mdsxyz123@yahoo.com>
> - Jean Delvare <jdelvare@suse.de>
> + - Mark Studebaker <mdsxyz123@yahoo.com>
> + - Jean Delvare <jdelvare@suse.de>
>
>
> Module Parameters
> -----------------
>
> * disable_features (bit vector)
> +
> Disable selected features normally supported by the device. This makes it
> possible to work around possible driver or hardware bugs if the feature in
> question doesn't work as intended for whatever reason. Bit values:
> +
> + ==== =========================================
> 0x01 disable SMBus PEC
> 0x02 disable the block buffer
> 0x08 disable the I2C block read functionality
> 0x10 don't use interrupts
> + ==== =========================================
>
>
> Description
> @@ -71,7 +79,7 @@ Pentium-based PCs, '815E' chipset, and others.
>
> The ICH chips contain at least SEVEN separate PCI functions in TWO logical
> PCI devices. An output of lspci will show something similar to the
> -following:
> +following::
>
> 00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01)
> 00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01)
> @@ -138,14 +146,14 @@ and you think there's something interesting on the SMBus (e.g. a
> hardware monitoring chip), you need to add your board to the list.
>
> The motherboard is identified using the subvendor and subdevice IDs of the
> -host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0":
> +host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``::
>
> -00:00.0 Class 0600: 8086:2570 (rev 02)
> - Subsystem: 1043:80f2
> - Flags: bus master, fast devsel, latency 0
> - Memory at fc000000 (32-bit, prefetchable) [size=32M]
> - Capabilities: [e4] #09 [2106]
> - Capabilities: [a0] AGP version 3.0
> + 00:00.0 Class 0600: 8086:2570 (rev 02)
> + Subsystem: 1043:80f2
> + Flags: bus master, fast devsel, latency 0
> + Memory at fc000000 (32-bit, prefetchable) [size=32M]
> + Capabilities: [e4] #09 [2106]
> + Capabilities: [a0] AGP version 3.0
>
> Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043
> (Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic
> @@ -164,7 +172,8 @@ kernel. It's very convenient if you just want to check if there's
> anything interesting on your hidden ICH SMBus.
>
>
> -**********************
> +----------------------------------------------------------------------------
> +
> The lm_sensors project gratefully acknowledges the support of Texas
> Instruments in the initial development of this driver.
>
> diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt.rst
> similarity index 81%
> rename from Documentation/i2c/busses/i2c-ismt
> rename to Documentation/i2c/busses/i2c-ismt.rst
> index 737355822c0b..8e74919a3fdf 100644
> --- a/Documentation/i2c/busses/i2c-ismt
> +++ b/Documentation/i2c/busses/i2c-ismt.rst
> @@ -1,4 +1,7 @@
> +======================
> Kernel driver i2c-ismt
> +======================
> +
>
> Supported adapters:
> * Intel S12xx series SOCs
> @@ -11,16 +14,21 @@ Module Parameters
> -----------------
>
> * bus_speed (unsigned int)
> +
> Allows changing of the bus speed. Normally, the bus speed is set by the BIOS
> and never needs to be changed. However, some SMBus analyzers are too slow for
> monitoring the bus during debug, thus the need for this module parameter.
> Specify the bus speed in kHz.
> +
> Available bus frequency settings:
> - 0 no change
> - 80 kHz
> - 100 kHz
> - 400 kHz
> - 1000 kHz
> +
> + ==== =========
> + 0 no change
> + 80 kHz
> + 100 kHz
> + 400 kHz
> + 1000 kHz
> + ==== =========
>
>
> Description
> @@ -30,7 +38,7 @@ The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers
> targeted primarily at the microserver and storage markets.
>
> The S12xx series contain a pair of PCI functions. An output of lspci will show
> -something similar to the following:
> +something similar to the following::
>
> 00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0
> 00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1
> diff --git a/Documentation/i2c/busses/i2c-mlxcpld b/Documentation/i2c/busses/i2c-mlxcpld.rst
> similarity index 88%
> rename from Documentation/i2c/busses/i2c-mlxcpld
> rename to Documentation/i2c/busses/i2c-mlxcpld.rst
> index 925904aa9b57..9a0b2916aa71 100644
> --- a/Documentation/i2c/busses/i2c-mlxcpld
> +++ b/Documentation/i2c/busses/i2c-mlxcpld.rst
> @@ -1,9 +1,12 @@
> +==================
> Driver i2c-mlxcpld
> +==================
>
> Author: Michael Shych <michaelsh@mellanox.com>
>
> This is the Mellanox I2C controller logic, implemented in Lattice CPLD
> device.
> +
> Device supports:
> - Master mode.
> - One physical bus.
> @@ -20,6 +23,8 @@ The next transaction types are supported:
> - Write Byte/Block.
>
> Registers:
> +
> +=============== === =======================================================================
> CPBLTY 0x0 - capability reg.
> Bits [6:5] - transaction length. b01 - 72B is supported,
> 36B in other case.
> @@ -49,3 +54,4 @@ DATAx 0xa - 0x54 - 68 bytes data buffer regs.
> For read transactions address is sent in a separate transaction and
> specified in the four first bytes (DATA0 - DATA3). Data is read
> starting from DATA0.
> +=============== === =======================================================================
> diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2.rst
> similarity index 68%
> rename from Documentation/i2c/busses/i2c-nforce2
> rename to Documentation/i2c/busses/i2c-nforce2.rst
> index 9698c396b830..f5c57ea31cd3 100644
> --- a/Documentation/i2c/busses/i2c-nforce2
> +++ b/Documentation/i2c/busses/i2c-nforce2.rst
> @@ -1,4 +1,6 @@
> +=========================
> Kernel driver i2c-nforce2
> +=========================
>
> Supported adapters:
> * nForce2 MCP 10de:0064
> @@ -16,26 +18,27 @@ Supported adapters:
> * nForce MCP78S 10de:0752
> * nForce MCP79 10de:0AA2
>
> -Datasheet: not publicly available, but seems to be similar to the
> +Datasheet:
> + not publicly available, but seems to be similar to the
> AMD-8111 SMBus 2.0 adapter.
>
> Authors:
> - Hans-Frieder Vogt <hfvogt@gmx.net>,
> - Thomas Leibold <thomas@plx.com>,
> - Patrick Dreker <patrick@dreker.de>
> + - Hans-Frieder Vogt <hfvogt@gmx.net>,
> + - Thomas Leibold <thomas@plx.com>,
> + - Patrick Dreker <patrick@dreker.de>
>
> Description
> -----------
>
> i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP.
>
> -If your 'lspci -v' listing shows something like the following,
> +If your ``lspci -v`` listing shows something like the following::
>
> -00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
> - Subsystem: Asustek Computer, Inc.: Unknown device 0c11
> - Flags: 66Mhz, fast devsel, IRQ 5
> - I/O ports at c000 [size=32]
> - Capabilities: <available only to root>
> + 00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
> + Subsystem: Asustek Computer, Inc.: Unknown device 0c11
> + Flags: 66Mhz, fast devsel, IRQ 5
> + I/O ports at c000 [size=32]
> + Capabilities: <available only to root>
>
> then this driver should support the SMBuses of your motherboard.
>
> diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
> similarity index 63%
> rename from Documentation/i2c/busses/i2c-nvidia-gpu
> rename to Documentation/i2c/busses/i2c-nvidia-gpu.rst
> index 31884d2b2eb5..38fb8a4c8756 100644
> --- a/Documentation/i2c/busses/i2c-nvidia-gpu
> +++ b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
> @@ -1,4 +1,6 @@
> +============================
> Kernel driver i2c-nvidia-gpu
> +============================
>
> Datasheet: not publicly available.
>
> @@ -11,8 +13,8 @@ Description
> i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing
> and later GPUs and it is used to communicate with Type-C controller on GPUs.
>
> -If your 'lspci -v' listing shows something like the following,
> +If your ``lspci -v`` listing shows something like the following::
>
> -01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
> + 01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
>
> then this driver should support the I2C controller of your GPU.
> diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores.rst
> similarity index 82%
> rename from Documentation/i2c/busses/i2c-ocores
> rename to Documentation/i2c/busses/i2c-ocores.rst
> index 9caaf7df1b2f..f5e175f2a2a6 100644
> --- a/Documentation/i2c/busses/i2c-ocores
> +++ b/Documentation/i2c/busses/i2c-ocores.rst
> @@ -1,4 +1,6 @@
> +========================
> Kernel driver i2c-ocores
> +========================
>
> Supported adapters:
> * OpenCores.org I2C controller by Richard Herveille (see datasheet link)
> @@ -23,9 +25,9 @@ distance between registers and the input clock speed.
> There is also a possibility to attach a list of i2c_board_info which
> the i2c-ocores driver will add to the bus upon creation.
>
> -E.G. something like:
> +E.G. something like::
>
> -static struct resource ocores_resources[] = {
> + static struct resource ocores_resources[] = {
> [0] = {
> .start = MYI2C_BASEADDR,
> .end = MYI2C_BASEADDR + 8,
> @@ -36,10 +38,10 @@ static struct resource ocores_resources[] = {
> .end = MYI2C_IRQ,
> .flags = IORESOURCE_IRQ,
> },
> -};
> + };
>
> -/* optional board info */
> -struct i2c_board_info ocores_i2c_board_info[] = {
> + /* optional board info */
> + struct i2c_board_info ocores_i2c_board_info[] = {
> {
> I2C_BOARD_INFO("tsc2003", 0x48),
> .platform_data = &tsc2003_platform_data,
> @@ -49,20 +51,20 @@ struct i2c_board_info ocores_i2c_board_info[] = {
> I2C_BOARD_INFO("adv7180", 0x42 >> 1),
> .irq = ADV_IRQ
> }
> -};
> + };
>
> -static struct ocores_i2c_platform_data myi2c_data = {
> + static struct ocores_i2c_platform_data myi2c_data = {
> .regstep = 2, /* two bytes between registers */
> .clock_khz = 50000, /* input clock of 50MHz */
> .devices = ocores_i2c_board_info, /* optional table of devices */
> .num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */
> -};
> + };
>
> -static struct platform_device myi2c = {
> + static struct platform_device myi2c = {
> .name = "ocores-i2c",
> .dev = {
> .platform_data = &myi2c_data,
> },
> .num_resources = ARRAY_SIZE(ocores_resources),
> .resource = ocores_resources,
> -};
> + };
> diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport
> deleted file mode 100644
> index c3dbb3bfd814..000000000000
> --- a/Documentation/i2c/busses/i2c-parport
> +++ /dev/null
> @@ -1,178 +0,0 @@
> -Kernel driver i2c-parport
> -
> -Author: Jean Delvare <jdelvare@suse.de>
> -
> -This is a unified driver for several i2c-over-parallel-port adapters,
> -such as the ones made by Philips, Velleman or ELV. This driver is
> -meant as a replacement for the older, individual drivers:
> - * i2c-philips-par
> - * i2c-elv
> - * i2c-velleman
> - * video/i2c-parport (NOT the same as this one, dedicated to home brew
> - teletext adapters)
> -
> -It currently supports the following devices:
> - * (type=0) Philips adapter
> - * (type=1) home brew teletext adapter
> - * (type=2) Velleman K8000 adapter
> - * (type=3) ELV adapter
> - * (type=4) Analog Devices ADM1032 evaluation board
> - * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
> - * (type=6) Barco LPT->DVI (K5800236) adapter
> - * (type=7) One For All JP1 parallel port adapter
> - * (type=8) VCT-jig
> -
> -These devices use different pinout configurations, so you have to tell
> -the driver what you have, using the type module parameter. There is no
> -way to autodetect the devices. Support for different pinout configurations
> -can be easily added when needed.
> -
> -Earlier kernels defaulted to type=0 (Philips). But now, if the type
> -parameter is missing, the driver will simply fail to initialize.
> -
> -SMBus alert support is available on adapters which have this line properly
> -connected to the parallel port's interrupt pin.
> -
> -
> -Building your own adapter
> --------------------------
> -
> -If you want to build you own i2c-over-parallel-port adapter, here is
> -a sample electronics schema (credits go to Sylvain Munaut):
> -
> -Device PC
> -Side ___________________Vdd (+) Side
> - | | |
> - --- --- ---
> - | | | | | |
> - |R| |R| |R|
> - | | | | | |
> - --- --- ---
> - | | |
> - | | /| |
> -SCL ----------x--------o |-----------x------------------- pin 2
> - | \| | |
> - | | |
> - | |\ | |
> -SDA ----------x----x---| o---x--------------------------- pin 13
> - | |/ |
> - | |
> - | /| |
> - ---------o |----------------x-------------- pin 3
> - \| | |
> - | |
> - --- ---
> - | | | |
> - |R| |R|
> - | | | |
> - --- ---
> - | |
> - ### ###
> - GND GND
> -
> -Remarks:
> - - This is the exact pinout and electronics used on the Analog Devices
> - evaluation boards.
> - /|
> - - All inverters -o |- must be 74HC05, they must be open collector output.
> - \|
> - - All resitors are 10k.
> - - Pins 18-25 of the parallel port connected to GND.
> - - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
> - The ADM1032 evaluation board uses D4-D7. Beware that the amount of
> - current you can draw from the parallel port is limited. Also note that
> - all connected lines MUST BE driven at the same state, else you'll short
> - circuit the output buffers! So plugging the I2C adapter after loading
> - the i2c-parport module might be a good safety since data line state
> - prior to init may be unknown.
> - - This is 5V!
> - - Obviously you cannot read SCL (so it's not really standard-compliant).
> - Pretty easy to add, just copy the SDA part and use another input pin.
> - That would give (ELV compatible pinout):
> -
> -
> -Device PC
> -Side ______________________________Vdd (+) Side
> - | | | |
> - --- --- --- ---
> - | | | | | | | |
> - |R| |R| |R| |R|
> - | | | | | | | |
> - --- --- --- ---
> - | | | |
> - | | |\ | |
> -SCL ----------x--------x--| o---x------------------------ pin 15
> - | | |/ |
> - | | |
> - | | /| |
> - | ---o |-------------x-------------- pin 2
> - | \| | |
> - | | |
> - | | |
> - | |\ | |
> -SDA ---------------x---x--| o--------x------------------- pin 10
> - | |/ |
> - | |
> - | /| |
> - ---o |------------------x--------- pin 3
> - \| | |
> - | |
> - --- ---
> - | | | |
> - |R| |R|
> - | | | |
> - --- ---
> - | |
> - ### ###
> - GND GND
> -
> -
> -If possible, you should use the same pinout configuration as existing
> -adapters do, so you won't even have to change the code.
> -
> -
> -Similar (but different) drivers
> --------------------------------
> -
> -This driver is NOT the same as the i2c-pport driver found in the i2c
> -package. The i2c-pport driver makes use of modern parallel port features so
> -that you don't need additional electronics. It has other restrictions
> -however, and was not ported to Linux 2.6 (yet).
> -
> -This driver is also NOT the same as the i2c-pcf-epp driver found in the
> -lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as
> -an I2C bus directly. Instead, it uses it to control an external I2C bus
> -master. That driver was not ported to Linux 2.6 (yet) either.
> -
> -
> -Legacy documentation for Velleman adapter
> ------------------------------------------
> -
> -Useful links:
> -Velleman http://www.velleman.be/
> -Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html
> -
> -The project has lead to new libs for the Velleman K8000 and K8005:
> - LIBK8000 v1.99.1 and LIBK8005 v0.21
> -With these libs, you can control the K8000 interface card and the K8005
> -stepper motor card with the simple commands which are in the original
> -Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
> -many more, using /dev/velleman.
> - http://home.wanadoo.nl/hihihi/libk8000.htm
> - http://home.wanadoo.nl/hihihi/libk8005.htm
> - http://struyve.mine.nu:8080/index.php?block=k8000
> - http://sourceforge.net/projects/libk8005/
> -
> -
> -One For All JP1 parallel port adapter
> --------------------------------------
> -
> -The JP1 project revolves around a set of remote controls which expose
> -the I2C bus their internal configuration EEPROM lives on via a 6 pin
> -jumper in the battery compartment. More details can be found at:
> -
> -http://www.hifi-remote.com/jp1/
> -
> -Details of the simple parallel port hardware can be found at:
> -
> -http://www.hifi-remote.com/jp1/hardware.shtml
> diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light.rst
> similarity index 92%
> rename from Documentation/i2c/busses/i2c-parport-light
> rename to Documentation/i2c/busses/i2c-parport-light.rst
> index 7071b8ba0af4..af85c8dfcd1a 100644
> --- a/Documentation/i2c/busses/i2c-parport-light
> +++ b/Documentation/i2c/busses/i2c-parport-light.rst
> @@ -1,4 +1,6 @@
> +===============================
> Kernel driver i2c-parport-light
> +===============================
>
> Author: Jean Delvare <jdelvare@suse.de>
>
> diff --git a/Documentation/i2c/busses/i2c-parport.rst b/Documentation/i2c/busses/i2c-parport.rst
> new file mode 100644
> index 000000000000..fae7c7ba9bd1
> --- /dev/null
> +++ b/Documentation/i2c/busses/i2c-parport.rst
> @@ -0,0 +1,190 @@
> +=========================
> +Kernel driver i2c-parport
> +=========================
> +
> +Author: Jean Delvare <jdelvare@suse.de>
> +
> +This is a unified driver for several i2c-over-parallel-port adapters,
> +such as the ones made by Philips, Velleman or ELV. This driver is
> +meant as a replacement for the older, individual drivers:
> +
> + * i2c-philips-par
> + * i2c-elv
> + * i2c-velleman
> + * video/i2c-parport
> + (NOT the same as this one, dedicated to home brew teletext adapters)
> +
> +It currently supports the following devices:
> +
> + * (type=0) Philips adapter
> + * (type=1) home brew teletext adapter
> + * (type=2) Velleman K8000 adapter
> + * (type=3) ELV adapter
> + * (type=4) Analog Devices ADM1032 evaluation board
> + * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
> + * (type=6) Barco LPT->DVI (K5800236) adapter
> + * (type=7) One For All JP1 parallel port adapter
> + * (type=8) VCT-jig
> +
> +These devices use different pinout configurations, so you have to tell
> +the driver what you have, using the type module parameter. There is no
> +way to autodetect the devices. Support for different pinout configurations
> +can be easily added when needed.
> +
> +Earlier kernels defaulted to type=0 (Philips). But now, if the type
> +parameter is missing, the driver will simply fail to initialize.
> +
> +SMBus alert support is available on adapters which have this line properly
> +connected to the parallel port's interrupt pin.
> +
> +
> +Building your own adapter
> +-------------------------
> +
> +If you want to build you own i2c-over-parallel-port adapter, here is
> +a sample electronics schema (credits go to Sylvain Munaut)::
> +
> + Device PC
> + Side ___________________Vdd (+) Side
> + | | |
> + --- --- ---
> + | | | | | |
> + |R| |R| |R|
> + | | | | | |
> + --- --- ---
> + | | |
> + | | /| |
> + SCL ----------x--------o |-----------x------------------- pin 2
> + | \| | |
> + | | |
> + | |\ | |
> + SDA ----------x----x---| o---x--------------------------- pin 13
> + | |/ |
> + | |
> + | /| |
> + ---------o |----------------x-------------- pin 3
> + \| | |
> + | |
> + --- ---
> + | | | |
> + |R| |R|
> + | | | |
> + --- ---
> + | |
> + ### ###
> + GND GND
> +
> +Remarks:
> + - This is the exact pinout and electronics used on the Analog Devices
> + evaluation boards.
> + - All inverters::
> +
> + /|
> + -o |-
> + \|
> +
> + must be 74HC05, they must be open collector output.
> + - All resitors are 10k.
> + - Pins 18-25 of the parallel port connected to GND.
> + - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
> + The ADM1032 evaluation board uses D4-D7. Beware that the amount of
> + current you can draw from the parallel port is limited. Also note that
> + all connected lines MUST BE driven at the same state, else you'll short
> + circuit the output buffers! So plugging the I2C adapter after loading
> + the i2c-parport module might be a good safety since data line state
> + prior to init may be unknown.
> + - This is 5V!
> + - Obviously you cannot read SCL (so it's not really standard-compliant).
> + Pretty easy to add, just copy the SDA part and use another input pin.
> + That would give (ELV compatible pinout)::
> +
> +
> + Device PC
> + Side ______________________________Vdd (+) Side
> + | | | |
> + --- --- --- ---
> + | | | | | | | |
> + |R| |R| |R| |R|
> + | | | | | | | |
> + --- --- --- ---
> + | | | |
> + | | |\ | |
> + SCL ----------x--------x--| o---x------------------------ pin 15
> + | | |/ |
> + | | |
> + | | /| |
> + | ---o |-------------x-------------- pin 2
> + | \| | |
> + | | |
> + | | |
> + | |\ | |
> + SDA ---------------x---x--| o--------x------------------- pin 10
> + | |/ |
> + | |
> + | /| |
> + ---o |------------------x--------- pin 3
> + \| | |
> + | |
> + --- ---
> + | | | |
> + |R| |R|
> + | | | |
> + --- ---
> + | |
> + ### ###
> + GND GND
> +
> +
> +If possible, you should use the same pinout configuration as existing
> +adapters do, so you won't even have to change the code.
> +
> +
> +Similar (but different) drivers
> +-------------------------------
> +
> +This driver is NOT the same as the i2c-pport driver found in the i2c
> +package. The i2c-pport driver makes use of modern parallel port features so
> +that you don't need additional electronics. It has other restrictions
> +however, and was not ported to Linux 2.6 (yet).
> +
> +This driver is also NOT the same as the i2c-pcf-epp driver found in the
> +lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as
> +an I2C bus directly. Instead, it uses it to control an external I2C bus
> +master. That driver was not ported to Linux 2.6 (yet) either.
> +
> +
> +Legacy documentation for Velleman adapter
> +-----------------------------------------
> +
> +Useful links:
> +
> +- Velleman http://www.velleman.be/
> +- Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html
> +
> +The project has lead to new libs for the Velleman K8000 and K8005:
> +
> + LIBK8000 v1.99.1 and LIBK8005 v0.21
> +
> +With these libs, you can control the K8000 interface card and the K8005
> +stepper motor card with the simple commands which are in the original
> +Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
> +many more, using /dev/velleman.
> +
> + - http://home.wanadoo.nl/hihihi/libk8000.htm
> + - http://home.wanadoo.nl/hihihi/libk8005.htm
> + - http://struyve.mine.nu:8080/index.php?block=k8000
> + - http://sourceforge.net/projects/libk8005/
> +
> +
> +One For All JP1 parallel port adapter
> +-------------------------------------
> +
> +The JP1 project revolves around a set of remote controls which expose
> +the I2C bus their internal configuration EEPROM lives on via a 6 pin
> +jumper in the battery compartment. More details can be found at:
> +
> +http://www.hifi-remote.com/jp1/
> +
> +Details of the simple parallel port hardware can be found at:
> +
> +http://www.hifi-remote.com/jp1/hardware.shtml
> diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa.rst
> similarity index 72%
> rename from Documentation/i2c/busses/i2c-pca-isa
> rename to Documentation/i2c/busses/i2c-pca-isa.rst
> index b044e5265488..a254010c8055 100644
> --- a/Documentation/i2c/busses/i2c-pca-isa
> +++ b/Documentation/i2c/busses/i2c-pca-isa.rst
> @@ -1,6 +1,9 @@
> +=========================
> Kernel driver i2c-pca-isa
> +=========================
>
> Supported adapters:
> +
> This driver supports ISA boards using the Philips PCA 9564
> Parallel bus to I2C bus controller
>
> @@ -10,11 +13,11 @@ Module Parameters
> -----------------
>
> * base int
> - I/O base address
> + I/O base address
> * irq int
> - IRQ interrupt
> + IRQ interrupt
> * clock int
> - Clock rate as described in table 1 of PCA9564 datasheet
> + Clock rate as described in table 1 of PCA9564 datasheet
>
> Description
> -----------
> diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4.rst
> similarity index 92%
> rename from Documentation/i2c/busses/i2c-piix4
> rename to Documentation/i2c/busses/i2c-piix4.rst
> index 2703bc3acad0..5d4744842b41 100644
> --- a/Documentation/i2c/busses/i2c-piix4
> +++ b/Documentation/i2c/busses/i2c-piix4.rst
> @@ -1,4 +1,6 @@
> +=======================
> Kernel driver i2c-piix4
> +=======================
>
> Supported adapters:
> * Intel 82371AB PIIX4 and PIIX4E
> @@ -21,8 +23,8 @@ Supported adapters:
> Datasheet: Publicly available at the SMSC website http://www.smsc.com
>
> Authors:
> - Frodo Looijaard <frodol@dds.nl>
> - Philip Edelbrock <phil@netroedge.com>
> + - Frodo Looijaard <frodol@dds.nl>
> + - Philip Edelbrock <phil@netroedge.com>
>
>
> Module Parameters
> @@ -45,10 +47,10 @@ natively understands SMBus commands and you do not have to worry about
> timing problems. The bad news is that non-SMBus devices connected to it can
> confuse it mightily. Yes, this is known to happen...
>
> -Do 'lspci -v' and see whether it contains an entry like this:
> +Do ``lspci -v`` and see whether it contains an entry like this::
>
> -0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
> - Flags: medium devsel, IRQ 9
> + 0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
> + Flags: medium devsel, IRQ 9
>
> Bus and device numbers may differ, but the function number must be
> identical (like many PCI devices, the PIIX4 incorporates a number of
> @@ -91,7 +93,7 @@ the SMI mode.
> device is located at 00:0f.0.
> 2) Now you just need to change the value in 0xD2 register. Get it first with
> command: lspci -xxx -s 00:0f.0
> - If the value is 0x3 then you need to change it to 0x1
> + If the value is 0x3 then you need to change it to 0x1:
> setpci -s 00:0f.0 d2.b=1
>
> Please note that you don't need to do that in all cases, just when the SMBus is
> diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595.rst
> similarity index 74%
> rename from Documentation/i2c/busses/i2c-sis5595
> rename to Documentation/i2c/busses/i2c-sis5595.rst
> index ecd21fb49a8f..5614afe35e79 100644
> --- a/Documentation/i2c/busses/i2c-sis5595
> +++ b/Documentation/i2c/busses/i2c-sis5595.rst
> @@ -1,9 +1,11 @@
> +=========================
> Kernel driver i2c-sis5595
> +=========================
>
> Authors:
> - Frodo Looijaard <frodol@dds.nl>,
> - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> - Philip Edelbrock <phil@netroedge.com>
> + - Frodo Looijaard <frodol@dds.nl>,
> + - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> + - Philip Edelbrock <phil@netroedge.com>
>
> Supported adapters:
> * Silicon Integrated Systems Corp. SiS5595 Southbridge
> @@ -11,14 +13,19 @@ Supported adapters:
>
> Note: all have mfr. ID 0x1039.
>
> + ========= ======
> SUPPORTED PCI ID
> + ========= ======
> 5595 0008
> + ========= ======
>
> Note: these chips contain a 0008 device which is incompatible with the
> 5595. We recognize these by the presence of the listed
> "blacklist" PCI ID and refuse to load.
>
> + ============= ====== ================
> NOT SUPPORTED PCI ID BLACKLIST PCI ID
> + ============= ====== ================
> 540 0008 0540
> 550 0008 0550
> 5513 0008 5511
> @@ -36,15 +43,18 @@ Note: all have mfr. ID 0x1039.
> 735 0008 0735
> 745 0008 0745
> 746 0008 0746
> + ============= ====== ================
>
> Module Parameters
> -----------------
>
> -* force_addr=0xaddr Set the I/O base address. Useful for boards
> +================== =====================================================
> +force_addr=0xaddr Set the I/O base address. Useful for boards
> that don't set the address in the BIOS. Does not do a
> PCI force; the device must still be present in lspci.
> Don't use this unless the driver complains that the
> base address is not set.
> +================== =====================================================
>
> Description
> -----------
> diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630
> deleted file mode 100644
> index ee7943631074..000000000000
> --- a/Documentation/i2c/busses/i2c-sis630
> +++ /dev/null
> @@ -1,58 +0,0 @@
> -Kernel driver i2c-sis630
> -
> -Supported adapters:
> - * Silicon Integrated Systems Corp (SiS)
> - 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux)
> - 730 chipset
> - 964 chipset
> - * Possible other SiS chipsets ?
> -
> -Author: Alexander Malysh <amalysh@web.de>
> - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
> -
> -Module Parameters
> ------------------
> -
> -* force = [1|0] Forcibly enable the SIS630. DANGEROUS!
> - This can be interesting for chipsets not named
> - above to check if it works for you chipset, but DANGEROUS!
> -
> -* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
> - what your BIOS use). DANGEROUS! This should be a bit
> - faster, but freeze some systems (i.e. my Laptop).
> - SIS630/730 chip only.
> -
> -
> -Description
> ------------
> -
> -This SMBus only driver is known to work on motherboards with the above
> -named chipsets.
> -
> -If you see something like this:
> -
> -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
> -00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> -
> -or like this:
> -
> -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
> -00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> -
> -or like this:
> -
> -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
> -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
> - LPC Controller (rev 36)
> -
> -in your 'lspci' output , then this driver is for your chipset.
> -
> -Thank You
> ----------
> -Philip Edelbrock <phil@netroedge.com>
> -- testing SiS730 support
> -Mark M. Hoffman <mhoffman@lightlink.com>
> -- bug fixes
> -
> -To anyone else which I forgot here ;), thanks!
> -
> diff --git a/Documentation/i2c/busses/i2c-sis630.rst b/Documentation/i2c/busses/i2c-sis630.rst
> new file mode 100644
> index 000000000000..f37700e885f2
> --- /dev/null
> +++ b/Documentation/i2c/busses/i2c-sis630.rst
> @@ -0,0 +1,64 @@
> +========================
> +Kernel driver i2c-sis630
> +========================
> +
> +Supported adapters:
> + * Silicon Integrated Systems Corp (SiS)
> + 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux)
> + 730 chipset
> + 964 chipset
> + * Possible other SiS chipsets ?
> +
> +Author:
> + - Alexander Malysh <amalysh@web.de>
> + - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
> +
> +Module Parameters
> +-----------------
> +
> +================== =====================================================
> +force = [1|0] Forcibly enable the SIS630. DANGEROUS!
> + This can be interesting for chipsets not named
> + above to check if it works for you chipset,
> + but DANGEROUS!
> +
> +high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
> + what your BIOS use). DANGEROUS! This should be a bit
> + faster, but freeze some systems (i.e. my Laptop).
> + SIS630/730 chip only.
> +================== =====================================================
> +
> +
> +Description
> +-----------
> +
> +This SMBus only driver is known to work on motherboards with the above
> +named chipsets.
> +
> +If you see something like this::
> +
> + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
> + 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> +
> +or like this::
> +
> + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
> + 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> +
> +or like this::
> +
> + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
> + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
> + LPC Controller (rev 36)
> +
> +in your ``lspci`` output , then this driver is for your chipset.
> +
> +Thank You
> +---------
> +Philip Edelbrock <phil@netroedge.com>
> +- testing SiS730 support
> +Mark M. Hoffman <mhoffman@lightlink.com>
> +- bug fixes
> +
> +To anyone else which I forgot here ;), thanks!
> +
> diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x.rst
> similarity index 75%
> rename from Documentation/i2c/busses/i2c-sis96x
> rename to Documentation/i2c/busses/i2c-sis96x.rst
> index 0b979f3252a4..b84581ade213 100644
> --- a/Documentation/i2c/busses/i2c-sis96x
> +++ b/Documentation/i2c/busses/i2c-sis96x.rst
> @@ -1,11 +1,16 @@
> +========================
> Kernel driver i2c-sis96x
> +========================
>
> Replaces 2.4.x i2c-sis645
>
> Supported adapters:
> +
> * Silicon Integrated Systems Corp (SiS)
> +
> Any combination of these host bridges:
> 645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746
> +
> and these south bridges:
> 961, 962, 963(L)
>
> @@ -21,17 +26,17 @@ those of the SiS630, although they are located in a completely different
> place. Thanks to Alexander Malysh <amalysh@web.de> for providing the
> SiS630 datasheet (and driver).
>
> -The command "lspci" as root should produce something like these lines:
> +The command ``lspci`` as root should produce something like these lines::
>
> -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
> -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> -00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
> + 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
> + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
> + 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
>
> -or perhaps this...
> +or perhaps this::
>
> -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
> -00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
> -00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
> + 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
> + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
> + 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
>
> (kernel versions later than 2.4.18 may fill in the "Unknown"s)
>
> @@ -50,7 +55,7 @@ TO DOs
> ------
>
> * The driver does not support SMBus block reads/writes; I may add them if a
> -scenario is found where they're needed.
> + scenario is found where they're needed.
>
>
> Thank You
> @@ -58,14 +63,19 @@ Thank You
>
> Mark D. Studebaker <mdsxyz123@yahoo.com>
> - design hints and bug fixes
> +
> Alexander Maylsh <amalysh@web.de>
> - ditto, plus an important datasheet... almost the one I really wanted
> +
> Hans-Günter Lütke Uphues <hg_lu@t-online.de>
> - patch for SiS735
> +
> Robert Zwerus <arzie@dds.nl>
> - testing for SiS645DX
> +
> Kianusch Sayah Karadji <kianusch@sk-tech.net>
> - patch for SiS645DX/962
> +
> Ken Healy
> - patch for SiS655
>
> diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm.rst
> similarity index 91%
> rename from Documentation/i2c/busses/i2c-taos-evm
> rename to Documentation/i2c/busses/i2c-taos-evm.rst
> index 60299555dcf0..f342e313ee3d 100644
> --- a/Documentation/i2c/busses/i2c-taos-evm
> +++ b/Documentation/i2c/busses/i2c-taos-evm.rst
> @@ -1,4 +1,6 @@
> +==========================
> Kernel driver i2c-taos-evm
> +==========================
>
> Author: Jean Delvare <jdelvare@suse.de>
>
> @@ -23,10 +25,10 @@ Using this driver
> In order to use this driver, you'll need the serport driver, and the
> inputattach tool, which is part of the input-utils package. The following
> commands will tell the kernel that you have a TAOS EVM on the first
> -serial port:
> +serial port::
>
> -# modprobe serport
> -# inputattach --taos-evm /dev/ttyS0
> + # modprobe serport
> + # inputattach --taos-evm /dev/ttyS0
>
>
> Technical details
> diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via.rst
> similarity index 61%
> rename from Documentation/i2c/busses/i2c-via
> rename to Documentation/i2c/busses/i2c-via.rst
> index 343870661ac3..df1df5adff7b 100644
> --- a/Documentation/i2c/busses/i2c-via
> +++ b/Documentation/i2c/busses/i2c-via.rst
> @@ -1,4 +1,6 @@
> +=====================
> Kernel driver i2c-via
> +=====================
>
> Supported adapters:
> * VIA Technologies, InC. VT82C586B
> @@ -15,20 +17,24 @@ The following VIA pci chipsets are supported:
> - MVP3, VP3, VP2/97, VPX/97
> - others with South bridge VT82C586B
>
> -Your lspci listing must show this :
> +Your ``lspci`` listing must show this ::
>
> Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10)
>
> - Problems?
> +Problems?
> +---------
>
> - Q: You have VT82C586B on the motherboard, but not in the listing.
> + Q:
> + You have VT82C586B on the motherboard, but not in the listing.
>
> - A: Go to your BIOS setup, section PCI devices or similar.
> + A:
> + Go to your BIOS setup, section PCI devices or similar.
> Turn USB support on, and try again.
>
> - Q: No error messages, but still i2c doesn't seem to work.
> + Q:
> + No error messages, but still i2c doesn't seem to work.
>
> - A: This can happen. This driver uses the pins VIA recommends in their
> + A:
> + This can happen. This driver uses the pins VIA recommends in their
> datasheets, but there are several ways the motherboard manufacturer
> can actually wire the lines.
> -
> diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro.rst
> similarity index 87%
> rename from Documentation/i2c/busses/i2c-viapro
> rename to Documentation/i2c/busses/i2c-viapro.rst
> index ab64ce21c254..1762f0cf93d0 100644
> --- a/Documentation/i2c/busses/i2c-viapro
> +++ b/Documentation/i2c/busses/i2c-viapro.rst
> @@ -1,4 +1,6 @@
> +========================
> Kernel driver i2c-viapro
> +========================
>
> Supported adapters:
> * VIA Technologies, Inc. VT82C596A/B
> @@ -26,9 +28,9 @@ Supported adapters:
> Datasheet: available on http://linux.via.com.tw
>
> Authors:
> - Kyösti Mälkki <kmalkki@cc.hut.fi>,
> - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> - Jean Delvare <jdelvare@suse.de>
> + - Kyösti Mälkki <kmalkki@cc.hut.fi>,
> + - Mark D. Studebaker <mdsxyz123@yahoo.com>,
> + - Jean Delvare <jdelvare@suse.de>
>
> Module Parameters
> -----------------
> @@ -44,8 +46,9 @@ Description
> i2c-viapro is a true SMBus host driver for motherboards with one of the
> supported VIA south bridges.
>
> -Your lspci -n listing must show one of these :
> +Your ``lspci -n`` listing must show one of these :
>
> + ================ ======================
> device 1106:3050 (VT82C596A function 3)
> device 1106:3051 (VT82C596B function 3)
> device 1106:3057 (VT82C686 function 4)
> @@ -61,6 +64,7 @@ Your lspci -n listing must show one of these :
> device 1106:8353 (VX800/VX820)
> device 1106:8409 (VX855/VX875)
> device 1106:8410 (VX900)
> + ================ ======================
>
> If none of these show up, you should look in the BIOS for settings like
> enable ACPI / SMBus or even USB.
> diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst
> new file mode 100644
> index 000000000000..97ca4d510816
> --- /dev/null
> +++ b/Documentation/i2c/busses/index.rst
> @@ -0,0 +1,33 @@
> +. SPDX-License-Identifier: GPL-2.0
> +
> +===============
> +I2C Bus Drivers
> +===============
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + i2c-ali1535
> + i2c-ali1563
> + i2c-ali15x3
> + i2c-amd756
> + i2c-amd8111
> + i2c-amd-mp2
> + i2c-diolan-u2c
> + i2c-i801
> + i2c-ismt
> + i2c-mlxcpld
> + i2c-nforce2
> + i2c-nvidia-gpu
> + i2c-ocores
> + i2c-parport-light
> + i2c-parport
> + i2c-pca-isa
> + i2c-piix4
> + i2c-sis5595
> + i2c-sis630
> + i2c-sis96x
> + i2c-taos-evm
> + i2c-viapro
> + i2c-via
> + scx200_acb
> diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb.rst
> similarity index 86%
> rename from Documentation/i2c/busses/scx200_acb
> rename to Documentation/i2c/busses/scx200_acb.rst
> index ce83c871fe95..8dc7c352508c 100644
> --- a/Documentation/i2c/busses/scx200_acb
> +++ b/Documentation/i2c/busses/scx200_acb.rst
> @@ -1,4 +1,6 @@
> +========================
> Kernel driver scx200_acb
> +========================
>
> Author: Christer Weinigel <wingel@nano-system.com>
>
> @@ -25,8 +27,11 @@ Device-specific notes
>
> The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820.
> If the scx200_acb driver is built into the kernel, add the following
> -parameter to your boot command line:
> +parameter to your boot command line::
> +
> scx200_acb.base=0x810,0x820
> +
> If the scx200_acb driver is built as a module, add the following line to
> -a configuration file in /etc/modprobe.d/ instead:
> +a configuration file in /etc/modprobe.d/ instead::
> +
> options scx200_acb base=0x810,0x820
> diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface.rst
> similarity index 71%
> rename from Documentation/i2c/dev-interface
> rename to Documentation/i2c/dev-interface.rst
> index fbed645ccd75..69c23a3c2b1b 100644
> --- a/Documentation/i2c/dev-interface
> +++ b/Documentation/i2c/dev-interface.rst
> @@ -1,3 +1,7 @@
> +====================
> +I2C Device Interface
> +====================
> +
> Usually, i2c devices are controlled by a kernel driver. But it is also
> possible to access all devices on an adapter from userspace, through
> the /dev interface. You need to load module i2c-dev for this.
> @@ -18,7 +22,7 @@ C example
> =========
>
> So let's say you want to access an i2c adapter from a C program.
> -First, you need to include these two headers:
> +First, you need to include these two headers::
>
> #include <linux/i2c-dev.h>
> #include <i2c/smbus.h>
> @@ -28,7 +32,7 @@ inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
> Adapter numbers are assigned somewhat dynamically, so you can not
> assume much about them. They can even change from one boot to the next.
>
> -Next thing, open the device file, as follows:
> +Next thing, open the device file, as follows::
>
> int file;
> int adapter_nr = 2; /* probably dynamically determined */
> @@ -42,7 +46,7 @@ Next thing, open the device file, as follows:
> }
>
> When you have opened the device, you must specify with what device
> -address you want to communicate:
> +address you want to communicate::
>
> int addr = 0x40; /* The I2C address */
>
> @@ -53,7 +57,7 @@ address you want to communicate:
>
> Well, you are all set up now. You can now use SMBus commands or plain
> I2C to communicate with your device. SMBus commands are preferred if
> -the device supports them. Both are illustrated below.
> +the device supports them. Both are illustrated below::
>
> __u8 reg = 0x10; /* Device register to access */
> __s32 res;
> @@ -100,35 +104,35 @@ Full interface description
>
> The following IOCTLs are defined:
>
> -ioctl(file, I2C_SLAVE, long addr)
> +``ioctl(file, I2C_SLAVE, long addr)``
> Change slave address. The address is passed in the 7 lower bits of the
> argument (except for 10 bit addresses, passed in the 10 lower bits in this
> case).
>
> -ioctl(file, I2C_TENBIT, long select)
> +``ioctl(file, I2C_TENBIT, long select)``
> Selects ten bit addresses if select not equals 0, selects normal 7 bit
> addresses if select equals 0. Default 0. This request is only valid
> if the adapter has I2C_FUNC_10BIT_ADDR.
>
> -ioctl(file, I2C_PEC, long select)
> +``ioctl(file, I2C_PEC, long select)``
> Selects SMBus PEC (packet error checking) generation and verification
> if select not equals 0, disables if select equals 0. Default 0.
> Used only for SMBus transactions. This request only has an effect if the
> the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just
> doesn't have any effect.
>
> -ioctl(file, I2C_FUNCS, unsigned long *funcs)
> - Gets the adapter functionality and puts it in *funcs.
> +``ioctl(file, I2C_FUNCS, unsigned long *funcs)``
> + Gets the adapter functionality and puts it in ``*funcs``.
>
> -ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
> +``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)``
> Do combined read/write transaction without stop in between.
> Only valid if the adapter has I2C_FUNC_I2C. The argument is
> - a pointer to a
> + a pointer to a::
>
> - struct i2c_rdwr_ioctl_data {
> + struct i2c_rdwr_ioctl_data {
> struct i2c_msg *msgs; /* ptr to array of simple messages */
> int nmsgs; /* number of messages to exchange */
> - }
> + }
>
> The msgs[] themselves contain further pointers into data buffers.
> The function will write or read data to or from that buffers depending
> @@ -136,8 +140,8 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
> The slave address and whether to use ten bit address mode has to be
> set in each message, overriding the values set with the above ioctl's.
>
> -ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)
> - If possible, use the provided i2c_smbus_* methods described below instead
> +``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)``
> + If possible, use the provided ``i2c_smbus_*`` methods described below instead
> of issuing direct ioctls.
>
> You can do plain i2c transactions by using read(2) and write(2) calls.
> @@ -145,7 +149,8 @@ You do not need to pass the address byte; instead, set it through
> ioctl I2C_SLAVE before you try to access the device.
>
> You can do SMBus level transactions (see documentation file smbus-protocol
> -for details) through the following functions:
> +for details) through the following functions::
> +
> __s32 i2c_smbus_write_quick(int file, __u8 value);
> __s32 i2c_smbus_read_byte(int file);
> __s32 i2c_smbus_write_byte(int file, __u8 value);
> @@ -157,6 +162,7 @@ for details) through the following functions:
> __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
> __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
> __u8 *values);
> +
> All these transactions return -1 on failure; you can read errno to see
> what happened. The 'write' transactions return 0 on success; the
> 'read' transactions return the read value, except for read_block, which
> @@ -174,39 +180,39 @@ Implementation details
> For the interested, here's the code flow which happens inside the kernel
> when you use the /dev interface to I2C:
>
> -1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in
> -section "C example" above.
> +1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in
> + section "C example" above.
>
> -2* These open() and ioctl() calls are handled by the i2c-dev kernel
> -driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
> -respectively. You can think of i2c-dev as a generic I2C chip driver
> -that can be programmed from user-space.
> +2) These open() and ioctl() calls are handled by the i2c-dev kernel
> + driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
> + respectively. You can think of i2c-dev as a generic I2C chip driver
> + that can be programmed from user-space.
>
> -3* Some ioctl() calls are for administrative tasks and are handled by
> -i2c-dev directly. Examples include I2C_SLAVE (set the address of the
> -device you want to access) and I2C_PEC (enable or disable SMBus error
> -checking on future transactions.)
> +3) Some ioctl() calls are for administrative tasks and are handled by
> + i2c-dev directly. Examples include I2C_SLAVE (set the address of the
> + device you want to access) and I2C_PEC (enable or disable SMBus error
> + checking on future transactions.)
>
> -4* Other ioctl() calls are converted to in-kernel function calls by
> -i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
> -functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
> -performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
> +4) Other ioctl() calls are converted to in-kernel function calls by
> + i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
> + functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
> + performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
>
> -The i2c-dev driver is responsible for checking all the parameters that
> -come from user-space for validity. After this point, there is no
> -difference between these calls that came from user-space through i2c-dev
> -and calls that would have been performed by kernel I2C chip drivers
> -directly. This means that I2C bus drivers don't need to implement
> -anything special to support access from user-space.
> + The i2c-dev driver is responsible for checking all the parameters that
> + come from user-space for validity. After this point, there is no
> + difference between these calls that came from user-space through i2c-dev
> + and calls that would have been performed by kernel I2C chip drivers
> + directly. This means that I2C bus drivers don't need to implement
> + anything special to support access from user-space.
>
> -5* These i2c.h functions are wrappers to the actual implementation of
> -your I2C bus driver. Each adapter must declare callback functions
> -implementing these standard calls. i2c.h:i2c_get_functionality() calls
> -i2c_adapter.algo->functionality(), while
> -i2c-core-smbus.c:i2c_smbus_xfer() calls either
> -adapter.algo->smbus_xfer() if it is implemented, or if not,
> -i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
> -i2c_adapter.algo->master_xfer().
> +5) These i2c.h functions are wrappers to the actual implementation of
> + your I2C bus driver. Each adapter must declare callback functions
> + implementing these standard calls. i2c.h:i2c_get_functionality() calls
> + i2c_adapter.algo->functionality(), while
> + i2c-core-smbus.c:i2c_smbus_xfer() calls either
> + adapter.algo->smbus_xfer() if it is implemented, or if not,
> + i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
> + i2c_adapter.algo->master_xfer().
>
> After your I2C bus driver has processed these requests, execution runs
> up the call chain, with almost no processing done, except by i2c-dev to
> diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/dma-considerations.rst
> similarity index 100%
> rename from Documentation/i2c/DMA-considerations
> rename to Documentation/i2c/dma-considerations.rst
> diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes.rst
> similarity index 98%
> rename from Documentation/i2c/fault-codes
> rename to Documentation/i2c/fault-codes.rst
> index 0cee0fc545b4..a09797588849 100644
> --- a/Documentation/i2c/fault-codes
> +++ b/Documentation/i2c/fault-codes.rst
> @@ -1,3 +1,7 @@
> +=====================
> +I2C/SMBUS Fault Codes
> +=====================
> +
> This is a summary of the most important conventions for use of fault
> codes in the I2C/SMBus stack.
>
> diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality.rst
> similarity index 91%
> rename from Documentation/i2c/functionality
> rename to Documentation/i2c/functionality.rst
> index 4aae8ed15873..7528c1ffd6ca 100644
> --- a/Documentation/i2c/functionality
> +++ b/Documentation/i2c/functionality.rst
> @@ -1,3 +1,7 @@
> +=======================
> +I2C/SMBus Functionality
> +=======================
> +
> INTRODUCTION
> ------------
>
> @@ -14,6 +18,7 @@ FUNCTIONALITY CONSTANTS
> For the most up-to-date list of functionality constants, please check
> <uapi/linux/i2c.h>!
>
> + =============================== ==============================================
> I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus
> adapters typically can not do these)
> I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions
> @@ -33,9 +38,11 @@ For the most up-to-date list of functionality constants, please check
> I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command
> I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command
> I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command
> + =============================== ==============================================
>
> A few combinations of the above flags are also defined for your convenience:
>
> + ========================= ======================================
> I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte
> and write_byte commands
> I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data
> @@ -49,6 +56,7 @@ A few combinations of the above flags are also defined for your convenience:
> I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be
> emulated by a real I2C adapter (using
> the transparent emulation layer)
> + ========================= ======================================
>
> In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as
> part of I2C_FUNC_PROTOCOL_MANGLING.
> @@ -58,11 +66,11 @@ ADAPTER IMPLEMENTATION
> ----------------------
>
> When you write a new adapter driver, you will have to implement a
> -function callback `functionality'. Typical implementations are given
> +function callback ``functionality``. Typical implementations are given
> below.
>
> A typical SMBus-only adapter would list all the SMBus transactions it
> -supports. This example comes from the i2c-piix4 driver:
> +supports. This example comes from the i2c-piix4 driver::
>
> static u32 piix4_func(struct i2c_adapter *adapter)
> {
> @@ -72,7 +80,7 @@ supports. This example comes from the i2c-piix4 driver:
> }
>
> A typical full-I2C adapter would use the following (from the i2c-pxa
> -driver):
> +driver)::
>
> static u32 i2c_pxa_functionality(struct i2c_adapter *adap)
> {
> @@ -94,7 +102,7 @@ CLIENT CHECKING
> Before a client tries to attach to an adapter, or even do tests to check
> whether one of the devices it supports is present on an adapter, it should
> check whether the needed functionality is present. The typical way to do
> -this is (from the lm75 driver):
> +this is (from the lm75 driver)::
>
> static int lm75_detect(...)
> {
> @@ -129,7 +137,7 @@ If you try to access an adapter from a userspace program, you will have
> to use the /dev interface. You will still have to check whether the
> functionality you need is supported, of course. This is done using
> the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is
> -below:
> +below::
>
> int file;
> if (file = open("/dev/i2c-0", O_RDWR) < 0) {
> diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection.rst
> similarity index 97%
> rename from Documentation/i2c/gpio-fault-injection
> rename to Documentation/i2c/gpio-fault-injection.rst
> index c87f416d53dd..9dca6ec7d266 100644
> --- a/Documentation/i2c/gpio-fault-injection
> +++ b/Documentation/i2c/gpio-fault-injection.rst
> @@ -104,10 +104,10 @@ There doesn't need to be a device at this address because arbitration lost
> should be detected beforehand. Also note, that SCL going down is monitored
> using interrupts, so the interrupt latency might cause the first bits to be not
> corrupted. A good starting point for using this fault injector on an otherwise
> -idle bus is:
> +idle bus is::
>
> -# echo 200 > lose_arbitration &
> -# i2cget -y <bus_to_test> 0x3f
> + # echo 200 > lose_arbitration &
> + # i2cget -y <bus_to_test> 0x3f
>
> Panic during transfer
> =====================
> @@ -127,10 +127,10 @@ The calling process will then sleep and wait for the next bus clock. The
> process is interruptible, though.
>
> Start of a transfer is detected by waiting for SCL going down by the master
> -under test. A good starting point for using this fault injector is:
> +under test. A good starting point for using this fault injector is::
>
> -# echo 0 > inject_panic &
> -# i2cget -y <bus_to_test> <some_address>
> + # echo 0 > inject_panic &
> + # i2cget -y <bus_to_test> <some_address>
>
> Note that there doesn't need to be a device listening to the address you are
> using. Results may vary depending on that, though.
> diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol.rst
> similarity index 83%
> rename from Documentation/i2c/i2c-protocol
> rename to Documentation/i2c/i2c-protocol.rst
> index ff6d6cee6c7e..2f8fcf671b2e 100644
> --- a/Documentation/i2c/i2c-protocol
> +++ b/Documentation/i2c/i2c-protocol.rst
> @@ -1,8 +1,13 @@
> +============
> +I2C Protocol
> +============
> +
> This document describes the i2c protocol. Or will, when it is finished :-)
>
> Key to symbols
> ==============
>
> +=============== =============================================================
> S (1 bit) : Start bit
> P (1 bit) : Stop bit
> Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
> @@ -15,33 +20,35 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
> for 16 bit data.
> Count (8 bits): A data byte containing the length of a block operation.
>
> -[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
> +[..]: Data sent by I2C device, as opposed to data sent by the
> + host adapter.
> +=============== =============================================================
>
>
> Simple send transaction
> -======================
> +=======================
>
> -This corresponds to i2c_master_send.
> +This corresponds to i2c_master_send::
>
> S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
>
>
> Simple receive transaction
> -===========================
> +==========================
>
> -This corresponds to i2c_master_recv
> +This corresponds to i2c_master_recv::
>
> S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
>
>
> Combined transactions
> -====================
> +=====================
>
> This corresponds to i2c_transfer
>
> They are just like the above transactions, but instead of a stop bit P
> a start bit S is sent and the transaction continues. An example of
> -a byte read, followed by a byte write:
> +a byte read, followed by a byte write::
>
> S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
>
> @@ -65,8 +72,10 @@ I2C_M_NO_RD_ACK:
> I2C_M_NOSTART:
> In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
> point. For example, setting I2C_M_NOSTART on the second partial message
> - generates something like:
> + generates something like::
> +
> S Addr Rd [A] [Data] NA Data [A] P
> +
> If you set the I2C_M_NOSTART variable for the first partial message,
> we do not generate Addr, but we do generate the startbit S. This will
> probably confuse all other clients on your bus, so don't try this.
> @@ -79,7 +88,8 @@ I2C_M_NOSTART:
> I2C_M_REV_DIR_ADDR:
> This toggles the Rd/Wr flag. That is, if you want to do a write, but
> need to emit an Rd instead of a Wr, or vice versa, you set this
> - flag. For example:
> + flag. For example::
> +
> S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
>
> I2C_M_STOP:
> diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub.rst
> similarity index 93%
> rename from Documentation/i2c/i2c-stub
> rename to Documentation/i2c/i2c-stub.rst
> index a16924fbd289..f8f194dfd379 100644
> --- a/Documentation/i2c/i2c-stub
> +++ b/Documentation/i2c/i2c-stub.rst
> @@ -1,6 +1,9 @@
> -MODULE: i2c-stub
> +========
> +i2c-stub
> +========
>
> -DESCRIPTION:
> +Description
> +===========
>
> This module is a very simple fake I2C/SMBus driver. It implements six
> types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w)
> @@ -28,6 +31,7 @@ SMBus block operations. Writes can be partial. Block read commands always
> return the number of bytes selected with the largest write so far.
>
> The typical use-case is like this:
> +
> 1. load this module
> 2. use i2cset (from the i2c-tools project) to pre-load some data
> 3. load the target chip driver module
> @@ -36,7 +40,8 @@ The typical use-case is like this:
> There's a script named i2c-stub-from-dump in the i2c-tools package which
> can load register values automatically from a chip dump.
>
> -PARAMETERS:
> +Parameters
> +==========
>
> int chip_addr[10]:
> The SMBus addresses to emulate chips at.
> @@ -47,14 +52,12 @@ unsigned long functionality:
> value 0x1f0000 would only enable the quick, byte and byte data
> commands.
>
> -u8 bank_reg[10]
> -u8 bank_mask[10]
> -u8 bank_start[10]
> -u8 bank_end[10]:
> +u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]:
> Optional bank settings. They tell which bits in which register
> select the active bank, as well as the range of banked registers.
>
> -CAVEATS:
> +Caveats
> +=======
>
> If your target driver polls some byte or word waiting for it to change, the
> stub could lock it up. Use i2cset to unlock it.
> diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology.rst
> similarity index 89%
> rename from Documentation/i2c/i2c-topology
> rename to Documentation/i2c/i2c-topology.rst
> index f74d78b53d4d..0c1ae95f6a97 100644
> --- a/Documentation/i2c/i2c-topology
> +++ b/Documentation/i2c/i2c-topology.rst
> @@ -1,3 +1,4 @@
> +============
> I2C topology
> ============
>
> @@ -14,6 +15,7 @@ than a straight-forward i2c bus with one adapter and one or more devices.
> that has to be operated before the device can be accessed.
>
> Etc
> +===
>
> These constructs are represented as i2c adapter trees by Linux, where
> each adapter has a parent adapter (except the root adapter) and zero or
> @@ -37,7 +39,9 @@ mux-locked or parent-locked muxes. As is evident from below, it can be
> useful to know if a mux is mux-locked or if it is parent-locked. The
> following list was correct at the time of writing:
>
> -In drivers/i2c/muxes/
> +In drivers/i2c/muxes/:
> +
> +====================== =============================================
> i2c-arb-gpio-challenge Parent-locked
> i2c-mux-gpio Normally parent-locked, mux-locked iff
> all involved gpio pins are controlled by the
> @@ -52,18 +56,25 @@ i2c-mux-pinctrl Normally parent-locked, mux-locked iff
> all involved pinctrl devices are controlled
> by the same i2c root adapter that they mux.
> i2c-mux-reg Parent-locked
> +====================== =============================================
>
> -In drivers/iio/
> +In drivers/iio/:
> +
> +====================== =============================================
> gyro/mpu3050 Mux-locked
> imu/inv_mpu6050/ Mux-locked
> +====================== =============================================
>
> -In drivers/media/
> +In drivers/media/:
> +
> +======================= =============================================
> dvb-frontends/lgdt3306a Mux-locked
> dvb-frontends/m88ds3103 Parent-locked
> dvb-frontends/rtl2830 Parent-locked
> dvb-frontends/rtl2832 Mux-locked
> dvb-frontends/si2168 Mux-locked
> usb/cx231xx/ Parent-locked
> +======================= =============================================
>
>
> Mux-locked muxes
> @@ -78,6 +89,7 @@ full transaction, unrelated i2c transfers may interleave the different
> stages of the transaction. This has the benefit that the mux driver
> may be easier and cleaner to implement, but it has some caveats.
>
> +==== =====================================================================
> ML1. If you build a topology with a mux-locked mux being the parent
> of a parent-locked mux, this might break the expectation from the
> parent-locked mux that the root adapter is locked during the
> @@ -105,11 +117,15 @@ ML4. If any non-i2c operation in the mux driver changes the i2c mux state,
> Otherwise garbage may appear on the bus as seen from devices
> behind the mux, when an unrelated i2c transfer is in flight during
> the non-i2c mux-changing operation.
> +==== =====================================================================
>
>
> Mux-locked Example
> ------------------
>
> +
> +::
> +
> .----------. .--------.
> .--------. | mux- |-----| dev D1 |
> | root |--+--| locked | '--------'
> @@ -148,6 +164,7 @@ adapter during the transaction are unlocked i2c transfers (using e.g.
> __i2c_transfer), or a deadlock will follow. There are a couple of
> caveats.
>
> +==== ====================================================================
> PL1. If you build a topology with a parent-locked mux being the child
> of another mux, this might break a possible assumption from the
> child mux that the root adapter is unused between its select op
> @@ -161,11 +178,14 @@ PL2. If select/deselect calls out to other subsystems such as gpio,
> caused by these subsystems are unlocked. This can be convoluted to
> accomplish, maybe even impossible if an acceptably clean solution
> is sought.
> +==== ====================================================================
>
>
> Parent-locked Example
> ---------------------
>
> +::
> +
> .----------. .--------.
> .--------. | parent- |-----| dev D1 |
> | root |--+--| locked | '--------'
> @@ -177,20 +197,20 @@ Parent-locked Example
>
> When there is an access to D1, this happens:
>
> - 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
> - 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
> - adapter.
> - 7. M1 calls ->deselect, if it has one.
> - 8. Same rules as in step 5, but for ->deselect.
> - 9. M1 unlocks its parent adapter.
> -10. M1 unlocks muxes on its parent.
> + 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
> + 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
> + adapter.
> + 7. M1 calls ->deselect, if it has one.
> + 8. Same rules as in step 5, but for ->deselect.
> + 9. M1 unlocks its parent adapter.
> + 10. M1 unlocks muxes on its parent.
>
>
> This means that accesses to both D2 and D3 are locked out for the full
> @@ -203,7 +223,7 @@ Complex Examples
> Parent-locked mux as parent of parent-locked mux
> ------------------------------------------------
>
> -This is a useful topology, but it can be bad.
> +This is a useful topology, but it can be bad::
>
> .----------. .----------. .--------.
> .--------. | parent- |-----| parent- |-----| dev D1 |
> @@ -227,7 +247,7 @@ through and be seen by the M2 adapter, thus closing M2 prematurely.
> Mux-locked mux as parent of mux-locked mux
> ------------------------------------------
>
> -This is a good topology.
> +This is a good topology::
>
> .----------. .----------. .--------.
> .--------. | mux- |-----| mux- |-----| dev D1 |
> @@ -248,7 +268,7 @@ are still possibly interleaved.
> Mux-locked mux as parent of parent-locked mux
> ---------------------------------------------
>
> -This is probably a bad topology.
> +This is probably a bad topology::
>
> .----------. .----------. .--------.
> .--------. | mux- |-----| parent- |-----| dev D1 |
> @@ -282,7 +302,7 @@ auto-closing, the topology is fine.
> Parent-locked mux as parent of mux-locked mux
> ---------------------------------------------
>
> -This is a good topology.
> +This is a good topology::
>
> .----------. .----------. .--------.
> .--------. | parent- |-----| mux- |-----| dev D1 |
> @@ -306,7 +326,7 @@ adapter is locked directly.
> Two mux-locked sibling muxes
> ----------------------------
>
> -This is a good topology.
> +This is a good topology::
>
> .--------.
> .----------. .--| dev D1 |
> @@ -330,7 +350,7 @@ accesses to D5 may be interleaved at any time.
> Two parent-locked sibling muxes
> -------------------------------
>
> -This is a good topology.
> +This is a good topology::
>
> .--------.
> .----------. .--| dev D1 |
> @@ -354,7 +374,7 @@ out.
> Mux-locked and parent-locked sibling muxes
> ------------------------------------------
>
> -This is a good topology.
> +This is a good topology::
>
> .--------.
> .----------. .--| dev D1 |
> diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
> new file mode 100644
> index 000000000000..d4ba671d0b55
> --- /dev/null
> +++ b/Documentation/i2c/index.rst
> @@ -0,0 +1,38 @@
> +. SPDX-License-Identifier: GPL-2.0
> +
> +===================
> +I2C/SMBus Subsystem
> +===================
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + dev-interface
> + dma-considerations
> + fault-codes
> + functionality
> + gpio-fault-injection
> + i2c-protocol
> + i2c-stub
> + i2c-topology
> + instantiating-devices
> + old-module-parameters
> + slave-eeprom-backend
> + slave-interface
> + smbus-protocol
> + summary
> + ten-bit-addresses
> + upgrading-clients
> + writing-clients
> +
> + muxes/i2c-mux-gpio
> +
> + busses/index
> +
> +.. only:: subproject and html
> +
> + Indices
> + =======
> +
> + * :ref:`genindex`
> +
> diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices.rst
> similarity index 93%
> rename from Documentation/i2c/instantiating-devices
> rename to Documentation/i2c/instantiating-devices.rst
> index 345e9ea8281a..1238f1fa3382 100644
> --- a/Documentation/i2c/instantiating-devices
> +++ b/Documentation/i2c/instantiating-devices.rst
> @@ -1,3 +1,4 @@
> +==============================
> How to instantiate I2C devices
> ==============================
>
> @@ -17,9 +18,9 @@ which is known in advance. It is thus possible to pre-declare the I2C
> devices which live on this bus. This is done with an array of struct
> i2c_board_info which is registered by calling i2c_register_board_info().
>
> -Example (from omap2 h4):
> +Example (from omap2 h4)::
>
> -static struct i2c_board_info h4_i2c_board_info[] __initdata = {
> + static struct i2c_board_info h4_i2c_board_info[] __initdata = {
> {
> I2C_BOARD_INFO("isp1301_omap", 0x2d),
> .irq = OMAP_GPIO_IRQ(125),
> @@ -32,15 +33,15 @@ static struct i2c_board_info h4_i2c_board_info[] __initdata = {
> I2C_BOARD_INFO("24c01", 0x57),
> .platform_data = &m24c01,
> },
> -};
> + };
>
> -static void __init omap_h4_init(void)
> -{
> + static void __init omap_h4_init(void)
> + {
> (...)
> i2c_register_board_info(1, h4_i2c_board_info,
> ARRAY_SIZE(h4_i2c_board_info));
> (...)
> -}
> + }
>
> The above code declares 3 devices on I2C bus 1, including their respective
> addresses and custom data needed by their drivers. When the I2C bus in
> @@ -57,7 +58,7 @@ Method 1b: Declare the I2C devices via devicetree
> This method has the same implications as method 1a. The declaration of I2C
> devices is here done via devicetree as subnodes of the master controller.
>
> -Example:
> +Example::
>
> i2c1: i2c@400a0000 {
> /* ... master properties skipped ... */
> @@ -99,20 +100,20 @@ bus in advance, so the method 1 described above can't be used. Instead,
> you can instantiate your I2C devices explicitly. This is done by filling
> a struct i2c_board_info and calling i2c_new_device().
>
> -Example (from the sfe4001 network driver):
> +Example (from the sfe4001 network driver)::
>
> -static struct i2c_board_info sfe4001_hwmon_info = {
> + static struct i2c_board_info sfe4001_hwmon_info = {
> I2C_BOARD_INFO("max6647", 0x4e),
> -};
> + };
>
> -int sfe4001_init(struct efx_nic *efx)
> -{
> + int sfe4001_init(struct efx_nic *efx)
> + {
> (...)
> efx->board_info.hwmon_client =
> i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info);
>
> (...)
> -}
> + }
>
> The above code instantiates 1 I2C device on the I2C bus which is on the
> network adapter in question.
> @@ -124,12 +125,12 @@ it may have different addresses from one board to the next (manufacturer
> changing its design without notice). In this case, you can call
> i2c_new_probed_device() instead of i2c_new_device().
>
> -Example (from the nxp OHCI driver):
> +Example (from the nxp OHCI driver)::
>
> -static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
> + static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
>
> -static int usb_hcd_nxp_probe(struct platform_device *pdev)
> -{
> + static int usb_hcd_nxp_probe(struct platform_device *pdev)
> + {
> (...)
> struct i2c_adapter *i2c_adap;
> struct i2c_board_info i2c_info;
> @@ -142,7 +143,7 @@ static int usb_hcd_nxp_probe(struct platform_device *pdev)
> normal_i2c, NULL);
> i2c_put_adapter(i2c_adap);
> (...)
> -}
> + }
>
> The above code instantiates up to 1 I2C device on the I2C bus which is on
> the OHCI adapter in question. It first tries at address 0x2c, if nothing
> @@ -172,6 +173,7 @@ explicitly. Instead, i2c-core will probe for such devices as soon as their
> drivers are loaded, and if any is found, an I2C device will be
> instantiated automatically. In order to prevent any misbehavior of this
> mechanism, the following restrictions apply:
> +
> * The I2C device driver must implement the detect() method, which
> identifies a supported device by reading from arbitrary registers.
> * Only buses which are likely to have a supported device and agree to be
> @@ -189,6 +191,7 @@ first.
> Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6
> kernels will find out that this method 3 is essentially similar to what
> was done there. Two significant differences are:
> +
> * Probing is only one way to instantiate I2C devices now, while it was the
> only way back then. Where possible, methods 1 and 2 should be preferred.
> Method 3 should only be used when there is no other way, as it can have
> @@ -224,11 +227,13 @@ device. As no two devices can live at the same address on a given I2C
> segment, the address is sufficient to uniquely identify the device to be
> deleted.
>
> -Example:
> -# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
> +Example::
> +
> + # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
>
> While this interface should only be used when in-kernel device declaration
> can't be done, there is a variety of cases where it can be helpful:
> +
> * The I2C driver usually detects devices (method 3 above) but the bus
> segment your device lives on doesn't have the proper class bit set and
> thus detection doesn't trigger.
> diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio.rst
> similarity index 85%
> rename from Documentation/i2c/muxes/i2c-mux-gpio
> rename to Documentation/i2c/muxes/i2c-mux-gpio.rst
> index 893ecdfe6e43..7d27444035c3 100644
> --- a/Documentation/i2c/muxes/i2c-mux-gpio
> +++ b/Documentation/i2c/muxes/i2c-mux-gpio.rst
> @@ -1,4 +1,6 @@
> +==========================
> Kernel driver i2c-mux-gpio
> +==========================
>
> Author: Peter Korsgaard <peter.korsgaard@barco.com>
>
> @@ -8,7 +10,7 @@ Description
> i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments
> from a master I2C bus and a hardware MUX controlled through GPIO pins.
>
> -E.G.:
> +E.G.::
>
> ---------- ---------- Bus segment 1 - - - - -
> | | SCL/SDA | |-------------- | |
> @@ -33,20 +35,20 @@ bus, the number of bus segments to create and the GPIO pins used
> to control it. See include/linux/platform_data/i2c-mux-gpio.h for details.
>
> E.G. something like this for a MUX providing 4 bus segments
> -controlled through 3 GPIO pins:
> +controlled through 3 GPIO pins::
>
> -#include <linux/platform_data/i2c-mux-gpio.h>
> -#include <linux/platform_device.h>
> + #include <linux/platform_data/i2c-mux-gpio.h>
> + #include <linux/platform_device.h>
>
> -static const unsigned myboard_gpiomux_gpios[] = {
> + static const unsigned myboard_gpiomux_gpios[] = {
> AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24
> -};
> + };
>
> -static const unsigned myboard_gpiomux_values[] = {
> + static const unsigned myboard_gpiomux_values[] = {
> 0, 1, 2, 3
> -};
> + };
>
> -static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
> + static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
> .parent = 1,
> .base_nr = 2, /* optional */
> .values = myboard_gpiomux_values,
> @@ -54,15 +56,15 @@ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
> .gpios = myboard_gpiomux_gpios,
> .n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios),
> .idle = 4, /* optional */
> -};
> + };
>
> -static struct platform_device myboard_i2cmux = {
> + static struct platform_device myboard_i2cmux = {
> .name = "i2c-mux-gpio",
> .id = 0,
> .dev = {
> .platform_data = &myboard_i2cmux_data,
> },
> -};
> + };
>
> If you don't know the absolute GPIO pin numbers at registration time,
> you can instead provide a chip name (.chip_name) and relative GPIO pin
> diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters.rst
> similarity index 75%
> rename from Documentation/i2c/old-module-parameters
> rename to Documentation/i2c/old-module-parameters.rst
> index 8e2b629d533c..a1939512ad66 100644
> --- a/Documentation/i2c/old-module-parameters
> +++ b/Documentation/i2c/old-module-parameters.rst
> @@ -1,3 +1,4 @@
> +=================================================
> I2C device driver binding control from user-space
> =================================================
>
> @@ -19,23 +20,27 @@ Below is a mapping from the old module parameters to the new interface.
> Attaching a driver to an I2C device
> -----------------------------------
>
> -Old method (module parameters):
> -# modprobe <driver> probe=1,0x2d
> -# modprobe <driver> force=1,0x2d
> -# modprobe <driver> force_<device>=1,0x2d
> +Old method (module parameters)::
>
> -New method (sysfs interface):
> -# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
> + # modprobe <driver> probe=1,0x2d
> + # modprobe <driver> force=1,0x2d
> + # modprobe <driver> force_<device>=1,0x2d
> +
> +New method (sysfs interface)::
> +
> + # echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
>
> Preventing a driver from attaching to an I2C device
> ---------------------------------------------------
>
> -Old method (module parameters):
> -# modprobe <driver> ignore=1,0x2f
> +Old method (module parameters)::
>
> -New method (sysfs interface):
> -# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
> -# modprobe <driver>
> + # modprobe <driver> ignore=1,0x2f
> +
> +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
> the driver. The dummy device will be handled by i2c-core itself, preventing
> diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend.rst
> similarity index 90%
> rename from Documentation/i2c/slave-eeprom-backend
> rename to Documentation/i2c/slave-eeprom-backend.rst
> index 04f8d8a9b817..2018fa74c6f3 100644
> --- a/Documentation/i2c/slave-eeprom-backend
> +++ b/Documentation/i2c/slave-eeprom-backend.rst
> @@ -1,3 +1,4 @@
> +==============================
> Linux I2C slave eeprom backend
> ==============================
>
> @@ -5,7 +6,7 @@ by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
>
> This is a proof-of-concept backend which acts like an EEPROM on the connected
> I2C bus. The memory contents can be modified from userspace via this file
> -located in sysfs:
> +located in sysfs::
>
> /sys/bus/i2c/devices/<device-directory>/slave-eeprom
>
> diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface.rst
> similarity index 94%
> rename from Documentation/i2c/slave-interface
> rename to Documentation/i2c/slave-interface.rst
> index 7e2a228f21bc..9ac5f110a4ec 100644
> --- a/Documentation/i2c/slave-interface
> +++ b/Documentation/i2c/slave-interface.rst
> @@ -1,3 +1,4 @@
> +=====================================
> Linux I2C slave interface description
> =====================================
>
> @@ -12,7 +13,7 @@ EEPROM, the Linux I2C slave can access the content via sysfs and handle data as
> needed. The backend driver and the I2C bus driver communicate via events. Here
> is a small graph visualizing the data flow and the means by which data is
> transported. The dotted line marks only one example. The backend could also
> -use a character device, be in-kernel only, or something completely different:
> +use a character device, be in-kernel only, or something completely different::
>
>
> e.g. sysfs I2C slave events I/O registers
> @@ -35,7 +36,7 @@ them as described in the document 'instantiating-devices'. The only difference
> is that i2c slave backends have their own address space. So, you have to add
> 0x1000 to the address you would originally request. An example for
> instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64
> -on bus 1:
> +on bus 1::
>
> # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device
>
> @@ -54,7 +55,7 @@ drivers and writing backends will be given.
> I2C slave events
> ----------------
>
> -The bus driver sends an event to the backend using the following function:
> +The bus driver sends an event to the backend using the following function::
>
> ret = i2c_slave_event(client, event, &val)
>
> @@ -69,8 +70,9 @@ Event types:
>
> * I2C_SLAVE_WRITE_REQUESTED (mandatory)
>
> -'val': unused
> -'ret': always 0
> + 'val': unused
> +
> + 'ret': always 0
>
> Another I2C master wants to write data to us. This event should be sent once
> our own address and the write bit was detected. The data did not arrive yet, so
> @@ -79,8 +81,9 @@ to be done, though.
>
> * I2C_SLAVE_READ_REQUESTED (mandatory)
>
> -'val': backend returns first byte to be sent
> -'ret': always 0
> + 'val': backend returns first byte to be sent
> +
> + 'ret': always 0
>
> Another I2C master wants to read data from us. This event should be sent once
> our own address and the read bit was detected. After returning, the bus driver
> @@ -88,8 +91,9 @@ should transmit the first byte.
>
> * I2C_SLAVE_WRITE_RECEIVED (mandatory)
>
> -'val': bus driver delivers received byte
> -'ret': 0 if the byte should be acked, some errno if the byte should be nacked
> + 'val': bus driver delivers received byte
> +
> + 'ret': 0 if the byte should be acked, some errno if the byte should be nacked
>
> Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
> is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
> @@ -97,8 +101,9 @@ should be nacked.
>
> * I2C_SLAVE_READ_PROCESSED (mandatory)
>
> -'val': backend returns next byte to be sent
> -'ret': always 0
> + 'val': backend returns next byte to be sent
> +
> + 'ret': always 0
>
> The bus driver requests the next byte to be sent to another I2C master in
> 'val'. Important: This does not mean that the previous byte has been acked, it
> @@ -111,8 +116,9 @@ your backend, though.
>
> * I2C_SLAVE_STOP (mandatory)
>
> -'val': unused
> -'ret': always 0
> + 'val': unused
> +
> + 'ret': always 0
>
> A stop condition was received. This can happen anytime and the backend should
> reset its state machine for I2C transfers to be able to receive new requests.
> diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol.rst
> similarity index 84%
> rename from Documentation/i2c/smbus-protocol
> rename to Documentation/i2c/smbus-protocol.rst
> index 092d474f5843..c6f189bfe1c7 100644
> --- a/Documentation/i2c/smbus-protocol
> +++ b/Documentation/i2c/smbus-protocol.rst
> @@ -1,3 +1,4 @@
> +======================
> SMBus Protocol Summary
> ======================
>
> @@ -27,12 +28,13 @@ Each transaction type corresponds to a functionality flag. Before calling a
> transaction function, a device driver should always check (just once) for
> the corresponding functionality flag to ensure that the underlying I2C
> adapter supports the transaction in question. See
> -<file:Documentation/i2c/functionality> for the details.
> +<file:Documentation/i2c/functionality.rst> for the details.
>
>
> Key to symbols
> ==============
>
> +=============== =============================================================
> S (1 bit) : Start bit
> P (1 bit) : Stop bit
> Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
> @@ -45,15 +47,17 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
> for 16 bit data.
> Count (8 bits): A data byte containing the length of a block operation.
>
> -[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
> +[..]: Data sent by I2C device, as opposed to data sent by the host
> + adapter.
> +=============== =============================================================
>
>
> SMBus Quick Command
> ===================
>
> -This sends a single bit to the device, at the place of the Rd/Wr bit.
> +This sends a single bit to the device, at the place of the Rd/Wr bit::
>
> -A Addr Rd/Wr [A] P
> + A Addr Rd/Wr [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_QUICK
>
> @@ -64,9 +68,9 @@ SMBus Receive Byte: i2c_smbus_read_byte()
> This reads a single byte from a device, without specifying a device
> register. Some devices are so simple that this interface is enough; for
> others, it is a shorthand if you want to read the same register as in
> -the previous SMBus command.
> +the previous SMBus command::
>
> -S Addr Rd [A] [Data] NA P
> + S Addr Rd [A] [Data] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_READ_BYTE
>
> @@ -77,7 +81,9 @@ SMBus Send Byte: i2c_smbus_write_byte()
> This operation is the reverse of Receive Byte: it sends a single byte
> to a device. See Receive Byte for more information.
>
> -S Addr Wr [A] Data [A] P
> +::
> +
> + S Addr Wr [A] Data [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE
>
> @@ -86,9 +92,9 @@ SMBus Read Byte: i2c_smbus_read_byte_data()
> ============================================
>
> This reads a single byte from a device, from a designated register.
> -The register is specified through the Comm byte.
> +The register is specified through the Comm byte::
>
> -S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
> + S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA
>
> @@ -98,9 +104,9 @@ SMBus Read Word: i2c_smbus_read_word_data()
>
> This operation is very like Read Byte; again, data is read from a
> device, from a designated register that is specified through the Comm
> -byte. But this time, the data is a complete word (16 bits).
> +byte. But this time, the data is a complete word (16 bits)::
>
> -S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
> + S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA
>
> @@ -116,7 +122,9 @@ This writes a single byte to a device, to a designated register. The
> register is specified through the Comm byte. This is the opposite of
> the Read Byte operation.
>
> -S Addr Wr [A] Comm [A] Data [A] P
> +::
> +
> + S Addr Wr [A] Comm [A] Data [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA
>
> @@ -126,9 +134,9 @@ SMBus Write Word: i2c_smbus_write_word_data()
>
> This is the opposite of the Read Word operation. 16 bits
> of data is written to a device, to the designated register that is
> -specified through the Comm byte.
> +specified through the Comm byte.::
>
> -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
> + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA
>
> @@ -141,10 +149,10 @@ SMBus Process Call:
> ===================
>
> This command selects a device register (through the Comm byte), sends
> -16 bits of data to it, and reads 16 bits of data in return.
> +16 bits of data to it, and reads 16 bits of data in return::
>
> -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
> - S Addr Rd [A] [DataLow] A [DataHigh] NA P
> + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
> + S Addr Rd [A] [DataLow] A [DataHigh] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
>
> @@ -156,8 +164,10 @@ This command reads a block of up to 32 bytes from a device, from a
> designated register that is specified through the Comm byte. The amount
> of data is specified by the device in the Count byte.
>
> -S Addr Wr [A] Comm [A]
> - S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
> +::
> +
> + S Addr Wr [A] Comm [A]
> + S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
>
> @@ -169,7 +179,9 @@ The opposite of the Block Read command, this writes up to 32 bytes to
> a device, to a designated register that is specified through the
> Comm byte. The amount of data is specified in the Count byte.
>
> -S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
> +::
> +
> + S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA
>
> @@ -181,10 +193,10 @@ SMBus Block Write - Block Read Process Call was introduced in
> Revision 2.0 of the specification.
>
> This command selects a device register (through the Comm byte), sends
> -1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return.
> +1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return::
>
> -S Addr Wr [A] Comm [A] Count [A] Data [A] ...
> - S Addr Rd [A] [Count] A [Data] ... A P
> + S Addr Wr [A] Comm [A] Count [A] Data [A] ...
> + S Addr Rd [A] [Count] A [Data] ... A P
>
> Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL
>
> @@ -197,9 +209,12 @@ SMBus host acting as a slave.
> It is the same form as Write Word, with the command code replaced by the
> alerting device's address.
>
> -[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
> +::
> +
> + [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
>
> This is implemented in the following way in the Linux kernel:
> +
> * I2C bus drivers which support SMBus Host Notify should report
> I2C_FUNC_SMBUS_HOST_NOTIFY.
> * I2C bus drivers trigger SMBus Host Notify by a call to
> @@ -241,6 +256,7 @@ single interrupt pin on the SMBus master, while still allowing the master
> to know which slave triggered the interrupt.
>
> This is implemented the following way in the Linux kernel:
> +
> * I2C bus drivers which support SMBus alert should call
> i2c_setup_smbus_alert() to setup SMBus alert support.
> * I2C drivers for devices which can trigger SMBus alerts should implement
> @@ -262,10 +278,10 @@ I2C Block Read: i2c_smbus_read_i2c_block_data()
> ================================================
>
> This command reads a block of bytes from a device, from a
> -designated register that is specified through the Comm byte.
> +designated register that is specified through the Comm byte::
>
> -S Addr Wr [A] Comm [A]
> - S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
> + S Addr Wr [A] Comm [A]
> + S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
>
> Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
>
> @@ -278,6 +294,8 @@ a device, to a designated register that is specified through the
> Comm byte. Note that command lengths of 0, 2, or more bytes are
> supported as they are indistinguishable from data.
>
> -S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
> +::
> +
> + S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
>
> Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK
> diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary.rst
> similarity index 96%
> rename from Documentation/i2c/summary
> rename to Documentation/i2c/summary.rst
> index 809541ab352f..8c08fa727f4e 100644
> --- a/Documentation/i2c/summary
> +++ b/Documentation/i2c/summary.rst
> @@ -1,3 +1,4 @@
> +=============
> I2C and SMBus
> =============
>
> @@ -24,7 +25,8 @@ implement all the common SMBus protocol semantics or messages.
> Terminology
> ===========
>
> -When we talk about I2C, we use the following terms:
> +When we talk about I2C, we use the following terms::
> +
> Bus -> Algorithm
> Adapter
> Device -> Driver
> diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses.rst
> similarity index 95%
> rename from Documentation/i2c/ten-bit-addresses
> rename to Documentation/i2c/ten-bit-addresses.rst
> index 7b2d11e53a49..5c765aff16d5 100644
> --- a/Documentation/i2c/ten-bit-addresses
> +++ b/Documentation/i2c/ten-bit-addresses.rst
> @@ -1,3 +1,7 @@
> +=====================
> +I2C Ten-bit Addresses
> +=====================
> +
> The I2C protocol knows about two kinds of device addresses: normal 7 bit
> addresses, and an extended set of 10 bit addresses. The sets of addresses
> do not intersect: the 7 bit address 0x10 is not the same as the 10 bit
> @@ -12,6 +16,7 @@ See the I2C specification for the details.
>
> The current 10 bit address support is minimal. It should work, however
> you can expect some problems along the way:
> +
> * Not all bus drivers support 10-bit addresses. Some don't because the
> hardware doesn't support them (SMBus doesn't require 10-bit address
> support for example), some don't because nobody bothered adding the
> diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients.rst
> similarity index 56%
> rename from Documentation/i2c/upgrading-clients
> rename to Documentation/i2c/upgrading-clients.rst
> index 96392cc5b5c7..4a575e607ff8 100644
> --- a/Documentation/i2c/upgrading-clients
> +++ b/Documentation/i2c/upgrading-clients.rst
> @@ -1,3 +1,4 @@
> +=================================================
> Upgrading I2C Drivers to the new 2.6 Driver Model
> =================================================
>
> @@ -13,21 +14,22 @@ the old to the new new binding methods.
> Example old-style driver
> ------------------------
>
> +::
>
> -struct example_state {
> + struct example_state {
> struct i2c_client client;
> ....
> -};
> + };
>
> -static struct i2c_driver example_driver;
> + static struct i2c_driver example_driver;
>
> -static unsigned short ignore[] = { I2C_CLIENT_END };
> -static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
> + static unsigned short ignore[] = { I2C_CLIENT_END };
> + static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
>
> -I2C_CLIENT_INSMOD;
> + I2C_CLIENT_INSMOD;
>
> -static int example_attach(struct i2c_adapter *adap, int addr, int kind)
> -{
> + static int example_attach(struct i2c_adapter *adap, int addr, int kind)
> + {
> struct example_state *state;
> struct device *dev = &adap->dev; /* to use for dev_ reports */
> int ret;
> @@ -59,23 +61,23 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind)
> dev_info(dev, "example client created\n");
>
> return 0;
> -}
> + }
>
> -static int example_detach(struct i2c_client *client)
> -{
> + static int example_detach(struct i2c_client *client)
> + {
> struct example_state *state = i2c_get_clientdata(client);
>
> i2c_detach_client(client);
> kfree(state);
> return 0;
> -}
> + }
>
> -static int example_attach_adapter(struct i2c_adapter *adap)
> -{
> + static int example_attach_adapter(struct i2c_adapter *adap)
> + {
> return i2c_probe(adap, &addr_data, example_attach);
> -}
> + }
>
> -static struct i2c_driver example_driver = {
> + static struct i2c_driver example_driver = {
> .driver = {
> .owner = THIS_MODULE,
> .name = "example",
> @@ -83,7 +85,7 @@ static struct i2c_driver example_driver = {
> },
> .attach_adapter = example_attach_adapter,
> .detach_client = example_detach,
> -};
> + };
>
>
> Updating the client
> @@ -93,38 +95,38 @@ The new style binding model will check against a list of supported
> devices and their associated address supplied by the code registering
> the busses. This means that the driver .attach_adapter and
> .detach_client methods can be removed, along with the addr_data,
> -as follows:
> +as follows::
>
> -- static struct i2c_driver example_driver;
> + - static struct i2c_driver example_driver;
>
> -- static unsigned short ignore[] = { I2C_CLIENT_END };
> -- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
> + - static unsigned short ignore[] = { I2C_CLIENT_END };
> + - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
>
> -- I2C_CLIENT_INSMOD;
> + - I2C_CLIENT_INSMOD;
>
> -- static int example_attach_adapter(struct i2c_adapter *adap)
> -- {
> -- return i2c_probe(adap, &addr_data, example_attach);
> -- }
> + - static int example_attach_adapter(struct i2c_adapter *adap)
> + - {
> + - return i2c_probe(adap, &addr_data, example_attach);
> + - }
>
> - static struct i2c_driver example_driver = {
> -- .attach_adapter = example_attach_adapter,
> -- .detach_client = example_detach,
> - }
> + static struct i2c_driver example_driver = {
> + - .attach_adapter = example_attach_adapter,
> + - .detach_client = example_detach,
> + }
>
> -Add the probe and remove methods to the i2c_driver, as so:
> +Add the probe and remove methods to the i2c_driver, as so::
>
> - static struct i2c_driver example_driver = {
> -+ .probe = example_probe,
> -+ .remove = example_remove,
> - }
> + static struct i2c_driver example_driver = {
> + + .probe = example_probe,
> + + .remove = example_remove,
> + }
>
> Change the example_attach method to accept the new parameters
> -which include the i2c_client that it will be working with:
> +which include the i2c_client that it will be working with::
>
> -- static int example_attach(struct i2c_adapter *adap, int addr, int kind)
> -+ static int example_probe(struct i2c_client *client,
> -+ const struct i2c_device_id *id)
> + - static int example_attach(struct i2c_adapter *adap, int addr, int kind)
> + + static int example_probe(struct i2c_client *client,
> + + const struct i2c_device_id *id)
>
> Change the name of example_attach to example_probe to align it with the
> i2c_driver entry names. The rest of the probe routine will now need to be
> @@ -132,55 +134,57 @@ changed as the i2c_client has already been setup for use.
>
> The necessary client fields have already been setup before
> the probe function is called, so the following client setup
> -can be removed:
> +can be removed::
>
> -- example->client.addr = addr;
> -- example->client.flags = 0;
> -- example->client.adapter = adap;
> --
> -- strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
> + - example->client.addr = addr;
> + - example->client.flags = 0;
> + - example->client.adapter = adap;
> + -
> + - strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
>
> -The i2c_set_clientdata is now:
> +The i2c_set_clientdata is now::
>
> -- i2c_set_clientdata(&state->client, state);
> -+ i2c_set_clientdata(client, state);
> + - i2c_set_clientdata(&state->client, state);
> + + i2c_set_clientdata(client, state);
>
> The call to i2c_attach_client is no longer needed, if the probe
> routine exits successfully, then the driver will be automatically
> -attached by the core. Change the probe routine as so:
> +attached by the core. Change the probe routine as so::
>
> -- ret = i2c_attach_client(&state->i2c_client);
> -- if (ret < 0) {
> -- dev_err(dev, "failed to attach client\n");
> -- kfree(state);
> -- return ret;
> -- }
> + - ret = i2c_attach_client(&state->i2c_client);
> + - if (ret < 0) {
> + - dev_err(dev, "failed to attach client\n");
> + - kfree(state);
> + - return ret;
> + - }
>
>
> Remove the storage of 'struct i2c_client' from the 'struct example_state'
> as we are provided with the i2c_client in our example_probe. Instead we
> store a pointer to it for when it is needed.
>
> -struct example_state {
> -- struct i2c_client client;
> -+ struct i2c_client *client;
> +::
>
> -the new i2c client as so:
> + struct example_state {
> + - struct i2c_client client;
> + + struct i2c_client *client;
>
> -- struct device *dev = &adap->dev; /* to use for dev_ reports */
> -+ struct device *dev = &i2c_client->dev; /* to use for dev_ reports */
> +the new i2c client as so::
> +
> + - struct device *dev = &adap->dev; /* to use for dev_ reports */
> + + struct device *dev = &i2c_client->dev; /* to use for dev_ reports */
>
> And remove the change after our client is attached, as the driver no
> -longer needs to register a new client structure with the core:
> +longer needs to register a new client structure with the core::
>
> -- dev = &state->i2c_client.dev;
> + - dev = &state->i2c_client.dev;
>
> In the probe routine, ensure that the new state has the client stored
> -in it:
> +in it::
>
> -static int example_probe(struct i2c_client *i2c_client,
> + static int example_probe(struct i2c_client *i2c_client,
> const struct i2c_device_id *id)
> -{
> + {
> struct example_state *state;
> struct device *dev = &i2c_client->dev;
> int ret;
> @@ -191,48 +195,50 @@ static int example_probe(struct i2c_client *i2c_client,
> return -ENOMEM;
> }
>
> -+ state->client = i2c_client;
> + + state->client = i2c_client;
>
> Update the detach method, by changing the name to _remove and
> to delete the i2c_detach_client call. It is possible that you
> can also remove the ret variable as it is not needed for any
> of the core functions.
>
> -- static int example_detach(struct i2c_client *client)
> -+ static int example_remove(struct i2c_client *client)
> -{
> +::
> +
> + - static int example_detach(struct i2c_client *client)
> + + static int example_remove(struct i2c_client *client)
> + {
> struct example_state *state = i2c_get_clientdata(client);
>
> -- i2c_detach_client(client);
> + - i2c_detach_client(client);
>
> And finally ensure that we have the correct ID table for the i2c-core
> -and other utilities:
> +and other utilities::
>
> -+ struct i2c_device_id example_idtable[] = {
> -+ { "example", 0 },
> -+ { }
> -+};
> -+
> -+MODULE_DEVICE_TABLE(i2c, example_idtable);
> + + struct i2c_device_id example_idtable[] = {
> + + { "example", 0 },
> + + { }
> + +};
> + +
> + +MODULE_DEVICE_TABLE(i2c, example_idtable);
>
> -static struct i2c_driver example_driver = {
> + static struct i2c_driver example_driver = {
> .driver = {
> .owner = THIS_MODULE,
> .name = "example",
> },
> -+ .id_table = example_ids,
> + + .id_table = example_ids,
>
>
> -Our driver should now look like this:
> +Our driver should now look like this::
>
> -struct example_state {
> + struct example_state {
> struct i2c_client *client;
> ....
> -};
> + };
>
> -static int example_probe(struct i2c_client *client,
> + static int example_probe(struct i2c_client *client,
> const struct i2c_device_id *id)
> -{
> + {
> struct example_state *state;
> struct device *dev = &client->dev;
>
> @@ -250,24 +256,24 @@ static int example_probe(struct i2c_client *client,
> dev_info(dev, "example client created\n");
>
> return 0;
> -}
> + }
>
> -static int example_remove(struct i2c_client *client)
> -{
> + static int example_remove(struct i2c_client *client)
> + {
> struct example_state *state = i2c_get_clientdata(client);
>
> kfree(state);
> return 0;
> -}
> + }
>
> -static struct i2c_device_id example_idtable[] = {
> + static struct i2c_device_id example_idtable[] = {
> { "example", 0 },
> { }
> -};
> + };
>
> -MODULE_DEVICE_TABLE(i2c, example_idtable);
> + MODULE_DEVICE_TABLE(i2c, example_idtable);
>
> -static struct i2c_driver example_driver = {
> + static struct i2c_driver example_driver = {
> .driver = {
> .owner = THIS_MODULE,
> .name = "example",
> @@ -276,4 +282,4 @@ static struct i2c_driver example_driver = {
> .id_table = example_idtable,
> .probe = example_probe,
> .remove = example_remove,
> -};
> + };
> diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients.rst
> similarity index 91%
> rename from Documentation/i2c/writing-clients
> rename to Documentation/i2c/writing-clients.rst
> index a755b141fa4a..dddf0a14ab7c 100644
> --- a/Documentation/i2c/writing-clients
> +++ b/Documentation/i2c/writing-clients.rst
> @@ -1,3 +1,7 @@
> +===================
> +Writing I2C Clients
> +===================
> +
> This is a small guide for those who want to write kernel drivers for I2C
> or SMBus devices, using Linux as the protocol host/master (not slave).
>
> @@ -12,7 +16,7 @@ General remarks
> Try to keep the kernel namespace as clean as possible. The best way to
> do this is to use a unique prefix for all global symbols. This is
> especially important for exported symbols, but it is a good idea to do
> -it for non-exported symbols too. We will use the prefix `foo_' in this
> +it for non-exported symbols too. We will use the prefix ``foo_`` in this
> tutorial.
>
>
> @@ -25,15 +29,17 @@ routines, and should be zero-initialized except for fields with data you
> provide. A client structure holds device-specific information like the
> driver model device node, and its I2C address.
>
> -static struct i2c_device_id foo_idtable[] = {
> +::
> +
> + static struct i2c_device_id foo_idtable[] = {
> { "foo", my_id_for_foo },
> { "bar", my_id_for_bar },
> { }
> -};
> + };
>
> -MODULE_DEVICE_TABLE(i2c, foo_idtable);
> + MODULE_DEVICE_TABLE(i2c, foo_idtable);
>
> -static struct i2c_driver foo_driver = {
> + static struct i2c_driver foo_driver = {
> .driver = {
> .name = "foo",
> .pm = &foo_pm_ops, /* optional */
> @@ -49,7 +55,7 @@ static struct i2c_driver foo_driver = {
>
> .shutdown = foo_shutdown, /* optional */
> .command = foo_command, /* optional, deprecated */
> -}
> + }
>
> The name field is the driver name, and must not contain spaces. It
> should match the module name (if the driver can be compiled as a module),
> @@ -64,16 +70,18 @@ below.
> Extra client data
> =================
>
> -Each client structure has a special `data' field that can point to any
> +Each client structure has a special ``data`` field that can point to any
> structure at all. You should use this to keep device-specific data.
>
> +::
> +
> /* store the value */
> void i2c_set_clientdata(struct i2c_client *client, void *data);
>
> /* retrieve the value */
> void *i2c_get_clientdata(const struct i2c_client *client);
>
> -Note that starting with kernel 2.6.34, you don't have to set the `data' field
> +Note that starting with kernel 2.6.34, you don't have to set the ``data`` field
> to NULL in remove() or if probe() failed anymore. The i2c-core does this
> automatically on these occasions. Those are also the only times the core will
> touch this field.
> @@ -92,25 +100,25 @@ but many chips have some kind of register-value idea that can easily
> be encapsulated.
>
> The below functions are simple examples, and should not be copied
> -literally.
> +literally::
>
> -int foo_read_value(struct i2c_client *client, u8 reg)
> -{
> + int foo_read_value(struct i2c_client *client, u8 reg)
> + {
> if (reg < 0x10) /* byte-sized register */
> return i2c_smbus_read_byte_data(client, reg);
> else /* word-sized register */
> return i2c_smbus_read_word_data(client, reg);
> -}
> + }
>
> -int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
> -{
> + int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
> + {
> if (reg == 0x10) /* Impossible to write - driver error! */
> return -EINVAL;
> else if (reg < 0x10) /* byte-sized register */
> return i2c_smbus_write_byte_data(client, reg, value);
> else /* word-sized register */
> return i2c_smbus_write_word_data(client, reg, value);
> -}
> + }
>
>
> Probing and attaching
> @@ -145,6 +153,8 @@ I2C device drivers using this binding model work just like any other
> kind of driver in Linux: they provide a probe() method to bind to
> those devices, and a remove() method to unbind.
>
> +::
> +
> static int foo_probe(struct i2c_client *client,
> const struct i2c_device_id *id);
> static int foo_remove(struct i2c_client *client);
> @@ -240,37 +250,41 @@ When the kernel is booted, or when your foo driver module is inserted,
> you have to do some initializing. Fortunately, just registering the
> driver module is usually enough.
>
> -static int __init foo_init(void)
> -{
> +::
> +
> + static int __init foo_init(void)
> + {
> return i2c_add_driver(&foo_driver);
> -}
> -module_init(foo_init);
> + }
> + module_init(foo_init);
>
> -static void __exit foo_cleanup(void)
> -{
> + static void __exit foo_cleanup(void)
> + {
> i2c_del_driver(&foo_driver);
> -}
> -module_exit(foo_cleanup);
> + }
> + module_exit(foo_cleanup);
>
> -The module_i2c_driver() macro can be used to reduce above code.
> + The module_i2c_driver() macro can be used to reduce above code.
>
> -module_i2c_driver(foo_driver);
> + module_i2c_driver(foo_driver);
>
> -Note that some functions are marked by `__init'. These functions can
> +Note that some functions are marked by ``__init``. These functions can
> be removed after kernel booting (or module loading) is completed.
> -Likewise, functions marked by `__exit' are dropped by the compiler when
> +Likewise, functions marked by ``__exit`` are dropped by the compiler when
> the code is built into the kernel, as they would never be called.
>
>
> Driver Information
> ==================
>
> -/* Substitute your own name and email address */
> -MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
> -MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
> +::
>
> -/* a few non-GPL license types are also allowed */
> -MODULE_LICENSE("GPL");
> + /* Substitute your own name and email address */
> + MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
> + MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
> +
> + /* a few non-GPL license types are also allowed */
> + MODULE_LICENSE("GPL");
>
>
> Power Management
> @@ -323,6 +337,8 @@ commands, but only some of them understand plain I2C!
> Plain I2C communication
> -----------------------
>
> +::
> +
> int i2c_master_send(struct i2c_client *client, const char *buf,
> int count);
> int i2c_master_recv(struct i2c_client *client, char *buf, int count);
> @@ -334,6 +350,8 @@ to read/write (must be less than the length of the buffer, also should be
> less than 64k since msg.len is u16.) Returned is the actual number of bytes
> read/written.
>
> +::
> +
> int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
> int num);
>
> @@ -343,13 +361,15 @@ stop bit is sent between transaction. The i2c_msg structure contains
> for each message the client address, the number of bytes of the message
> and the message data itself.
>
> -You can read the file `i2c-protocol' for more information about the
> +You can read the file ``i2c-protocol`` for more information about the
> actual I2C protocol.
>
>
> SMBus communication
> -------------------
>
> +::
> +
> s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
> unsigned short flags, char read_write, u8 command,
> int size, union i2c_smbus_data *data);
> @@ -357,6 +377,8 @@ SMBus communication
> This is the generic SMBus function. All functions below are implemented
> in terms of it. Never use this function directly!
>
> +::
> +
> s32 i2c_smbus_read_byte(struct i2c_client *client);
> s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);
> s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);
> @@ -376,7 +398,7 @@ in terms of it. Never use this function directly!
> const u8 *values);
>
> These ones were removed from i2c-core because they had no users, but could
> -be added back later if needed:
> +be added back later if needed::
>
> s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);
> s32 i2c_smbus_process_call(struct i2c_client *client,
> @@ -389,7 +411,7 @@ transactions return 0 on success; the 'read' transactions return the read
> value, except for block transactions, which return the number of values
> read. The block buffers need not be longer than 32 bytes.
>
> -You can read the file `smbus-protocol' for more information about the
> +You can read the file ``smbus-protocol`` for more information about the
> actual SMBus protocol.
>
>
> @@ -397,7 +419,7 @@ General purpose routines
> ========================
>
> Below all general purpose routines are listed, that were not mentioned
> -before.
> +before::
>
> /* Return the adapter number for a specific adapter */
> int i2c_adapter_id(struct i2c_adapter *adap);
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 13c3188f6a68..ded1081e8d5f 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -104,6 +104,7 @@ needed).
> fb/index
> fpga/index
> hid/index
> + i2c/index
> iio/index
> infiniband/index
> leds/index
> diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602
> index a45702865a38..0feffd5af411 100644
> --- a/Documentation/spi/spi-sc18is602
> +++ b/Documentation/spi/spi-sc18is602
> @@ -17,7 +17,7 @@ kernel's SPI core subsystem.
>
> The driver does not probe for supported chips, since the SI18IS602/603 does not
> support Chip ID registers. You will have to instantiate the devices explicitly.
> -Please see Documentation/i2c/instantiating-devices for details.
> +Please see Documentation/i2c/instantiating-devices.rst for details.
>
>
> Usage Notes
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 5d4da1035a03..ce925b6e3bcc 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -666,7 +666,7 @@ ALI1563 I2C DRIVER
> M: Rudolf Marek <r.marek@assembler.cz>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/busses/i2c-ali1563
> +F: Documentation/i2c/busses/i2c-ali1563.rst
> F: drivers/i2c/busses/i2c-ali1563.c
>
> ALLEGRO DVT VIDEO IP CORE DRIVER
> @@ -6657,7 +6657,7 @@ L: linux-i2c@vger.kernel.org
> S: Supported
> F: drivers/i2c/muxes/i2c-mux-gpio.c
> F: include/linux/platform_data/i2c-mux-gpio.h
> -F: Documentation/i2c/muxes/i2c-mux-gpio
> +F: Documentation/i2c/muxes/i2c-mux-gpio.rst
>
> GENERIC HDLC (WAN) DRIVERS
> M: Krzysztof Halasa <khc@pm.waw.pl>
> @@ -7393,14 +7393,14 @@ I2C CONTROLLER DRIVER FOR NVIDIA GPU
> M: Ajay Gupta <ajayg@nvidia.com>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/busses/i2c-nvidia-gpu
> +F: Documentation/i2c/busses/i2c-nvidia-gpu.rst
> F: drivers/i2c/busses/i2c-nvidia-gpu.c
>
> I2C MUXES
> M: Peter Rosin <peda@axentia.se>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/i2c-topology
> +F: Documentation/i2c/i2c-topology.rst
> F: Documentation/i2c/muxes/
> F: Documentation/devicetree/bindings/i2c/i2c-mux*
> F: Documentation/devicetree/bindings/i2c/i2c-arb*
> @@ -7420,8 +7420,8 @@ I2C OVER PARALLEL PORT
> M: Jean Delvare <jdelvare@suse.com>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/busses/i2c-parport
> -F: Documentation/i2c/busses/i2c-parport-light
> +F: Documentation/i2c/busses/i2c-parport.rst
> +F: Documentation/i2c/busses/i2c-parport-light.rst
> F: drivers/i2c/busses/i2c-parport.c
> F: drivers/i2c/busses/i2c-parport-light.c
>
> @@ -7455,7 +7455,7 @@ I2C-TAOS-EVM DRIVER
> M: Jean Delvare <jdelvare@suse.com>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/busses/i2c-taos-evm
> +F: Documentation/i2c/busses/i2c-taos-evm.rst
> F: drivers/i2c/busses/i2c-taos-evm.c
>
> I2C-TINY-USB DRIVER
> @@ -7469,19 +7469,19 @@ I2C/SMBUS CONTROLLER DRIVERS FOR PC
> M: Jean Delvare <jdelvare@suse.com>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> -F: Documentation/i2c/busses/i2c-ali1535
> -F: Documentation/i2c/busses/i2c-ali1563
> -F: Documentation/i2c/busses/i2c-ali15x3
> -F: Documentation/i2c/busses/i2c-amd756
> -F: Documentation/i2c/busses/i2c-amd8111
> -F: Documentation/i2c/busses/i2c-i801
> -F: Documentation/i2c/busses/i2c-nforce2
> -F: Documentation/i2c/busses/i2c-piix4
> -F: Documentation/i2c/busses/i2c-sis5595
> -F: Documentation/i2c/busses/i2c-sis630
> -F: Documentation/i2c/busses/i2c-sis96x
> -F: Documentation/i2c/busses/i2c-via
> -F: Documentation/i2c/busses/i2c-viapro
> +F: Documentation/i2c/busses/i2c-ali1535.rst
> +F: Documentation/i2c/busses/i2c-ali1563.rst
> +F: Documentation/i2c/busses/i2c-ali15x3.rst
> +F: Documentation/i2c/busses/i2c-amd756.rst
> +F: Documentation/i2c/busses/i2c-amd8111.rst
> +F: Documentation/i2c/busses/i2c-i801.rst
> +F: Documentation/i2c/busses/i2c-nforce2.rst
> +F: Documentation/i2c/busses/i2c-piix4.rst
> +F: Documentation/i2c/busses/i2c-sis5595.rst
> +F: Documentation/i2c/busses/i2c-sis630.rst
> +F: Documentation/i2c/busses/i2c-sis96x.rst
> +F: Documentation/i2c/busses/i2c-via.rst
> +F: Documentation/i2c/busses/i2c-viapro.rst
> F: drivers/i2c/busses/i2c-ali1535.c
> F: drivers/i2c/busses/i2c-ali1563.c
> F: drivers/i2c/busses/i2c-ali15x3.c
> @@ -7510,7 +7510,7 @@ M: Seth Heasley <seth.heasley@intel.com>
> M: Neil Horman <nhorman@tuxdriver.com>
> L: linux-i2c@vger.kernel.org
> F: drivers/i2c/busses/i2c-ismt.c
> -F: Documentation/i2c/busses/i2c-ismt
> +F: Documentation/i2c/busses/i2c-ismt.rst
>
> I2C/SMBUS STUB DRIVER
> M: Jean Delvare <jdelvare@suse.com>
> @@ -10236,7 +10236,7 @@ L: linux-i2c@vger.kernel.org
> S: Supported
> F: drivers/i2c/busses/i2c-mlxcpld.c
> F: drivers/i2c/muxes/i2c-mux-mlxcpld.c
> -F: Documentation/i2c/busses/i2c-mlxcpld
> +F: Documentation/i2c/busses/i2c-mlxcpld.rst
>
> MELLANOX MLXCPLD LED DRIVER
> M: Vadim Pasternak <vadimp@mellanox.com>
> @@ -11857,7 +11857,7 @@ M: Andrew Lunn <andrew@lunn.ch>
> L: linux-i2c@vger.kernel.org
> S: Maintained
> F: Documentation/devicetree/bindings/i2c/i2c-ocores.txt
> -F: Documentation/i2c/busses/i2c-ocores
> +F: Documentation/i2c/busses/i2c-ocores.rst
> F: drivers/i2c/busses/i2c-ocores.c
> F: include/linux/platform_data/i2c-ocores.h
>
> @@ -14141,7 +14141,7 @@ F: net/sctp/
> SCx200 CPU SUPPORT
> M: Jim Cromie <jim.cromie@gmail.com>
> S: Odd Fixes
> -F: Documentation/i2c/busses/scx200_acb
> +F: Documentation/i2c/busses/scx200_acb.rst
> F: arch/x86/platform/scx200/
> F: drivers/watchdog/scx200_wdt.c
> F: drivers/i2c/busses/scx200*
> diff --git a/Next/merge.log b/Next/merge.log
> index e9f5123f59ca..b45b3201b1d6 100644
> --- a/Next/merge.log
> +++ b/Next/merge.log
> @@ -2954,7 +2954,7 @@ $ git diff -M --stat --summary HEAD^..
> Documentation/devicetree/bindings/i2c/i2c-omap.txt | 1 +
> .../devicetree/bindings/i2c/i2c-sun6i-p2wi.txt | 41 ---
> .../bindings/i2c/marvell,mv64xxx-i2c.yaml | 124 +++++++
> - Documentation/i2c/busses/i2c-i801 | 3 +-
> + Documentation/i2c/busses/i2c-i801.rst | 3 +-
> MAINTAINERS | 7 +
> arch/arm/include/asm/hardware/iop3xx.h | 2 +
> arch/arm/mach-iop32x/em7210.c | 3 +
> @@ -3251,8 +3251,8 @@ $ git diff -M --stat --summary HEAD^..
> Documentation/fpga/index.rst | 17 +
> Documentation/gpu/msm-crash-dump.rst | 2 +
> Documentation/hid/hid-transport.txt | 6 +-
> - Documentation/i2c/instantiating-devices | 4 +-
> - Documentation/i2c/upgrading-clients | 4 +-
> + Documentation/i2c/instantiating-devices.rst | 4 +-
> + Documentation/i2c/upgrading-clients.rst | 4 +-
> Documentation/ide/changelogs.rst | 17 +
> Documentation/ide/{ide-tape.txt => ide-tape.rst} | 23 +-
> Documentation/ide/{ide.txt => ide.rst} | 147 +-
> diff --git a/drivers/hwmon/atxp1.c b/drivers/hwmon/atxp1.c
> index e232fa948833..79b8df258371 100644
> --- a/drivers/hwmon/atxp1.c
> +++ b/drivers/hwmon/atxp1.c
> @@ -5,7 +5,7 @@
> *
> * The ATXP1 can reside on I2C addresses 0x37 or 0x4e. The chip is
> * not auto-detected by the driver and must be instantiated explicitly.
> - * See Documentation/i2c/instantiating-devices for more information.
> + * See Documentation/i2c/instantiating-devices.rst for more information.
> */
>
> #include <linux/kernel.h>
> diff --git a/drivers/hwmon/smm665.c b/drivers/hwmon/smm665.c
> index d8c91c2cb8cf..9ae0dc28b9cf 100644
> --- a/drivers/hwmon/smm665.c
> +++ b/drivers/hwmon/smm665.c
> @@ -197,7 +197,7 @@ static int smm665_read_adc(struct smm665_data *data, int adc)
> if (rv != -ENXIO) {
> /*
> * We expect ENXIO to reflect NACK
> - * (per Documentation/i2c/fault-codes).
> + * (per Documentation/i2c/fault-codes.rst).
> * Everything else is an error.
> */
> dev_dbg(&client->dev,
> diff --git a/drivers/i2c/Kconfig b/drivers/i2c/Kconfig
> index abedd55a1264..1474e57ecafc 100644
> --- a/drivers/i2c/Kconfig
> +++ b/drivers/i2c/Kconfig
> @@ -54,7 +54,7 @@ config I2C_CHARDEV
> Say Y here to use i2c-* device files, usually found in the /dev
> directory on your system. They make it possible to have user-space
> programs use the I2C bus. Information on how to do this is
> - contained in the file <file:Documentation/i2c/dev-interface>.
> + contained in the file <file:Documentation/i2c/dev-interface.rst>.
>
> This support is also available as a module. If so, the module
> will be called i2c-dev.
> @@ -107,7 +107,7 @@ config I2C_STUB
> especially for certain kinds of sensor chips.
>
> If you do build this module, be sure to read the notes and warnings
> - in <file:Documentation/i2c/i2c-stub>.
> + in <file:Documentation/i2c/i2c-stub.rst>.
>
> If you don't know what to do here, definitely say N.
>
> diff --git a/drivers/i2c/busses/Kconfig b/drivers/i2c/busses/Kconfig
> index 68b677be1fa4..e4be46644e8b 100644
> --- a/drivers/i2c/busses/Kconfig
> +++ b/drivers/i2c/busses/Kconfig
> @@ -1205,7 +1205,7 @@ config I2C_PARPORT
> and makes it easier to add support for new devices.
>
> An adapter type parameter is now mandatory. Please read the file
> - Documentation/i2c/busses/i2c-parport for details.
> + Documentation/i2c/busses/i2c-parport.rst for details.
>
> Another driver exists, named i2c-parport-light, which doesn't depend
> on the parport driver. This is meant for embedded systems. Don't say
> diff --git a/drivers/i2c/busses/i2c-i801.c b/drivers/i2c/busses/i2c-i801.c
> index 1e7f6ae62b4c..a215b336bf5c 100644
> --- a/drivers/i2c/busses/i2c-i801.c
> +++ b/drivers/i2c/busses/i2c-i801.c
> @@ -76,7 +76,7 @@
> * SMBus Host Notify yes
> * Interrupt processing yes
> *
> - * See the file Documentation/i2c/busses/i2c-i801 for details.
> + * See the file Documentation/i2c/busses/i2c-i801.rst for details.
> */
>
> #include <linux/interrupt.h>
> diff --git a/drivers/i2c/busses/i2c-taos-evm.c b/drivers/i2c/busses/i2c-taos-evm.c
> index c82e78f57386..37347c93e8e0 100644
> --- a/drivers/i2c/busses/i2c-taos-evm.c
> +++ b/drivers/i2c/busses/i2c-taos-evm.c
> @@ -125,7 +125,7 @@ static int taos_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
> /*
> * Voluntarily dropping error code of kstrtou8 since all
> * error code that it could return are invalid according
> - * to Documentation/i2c/fault-codes.
> + * to Documentation/i2c/fault-codes.rst.
> */
> if (kstrtou8(p + 1, 16, &data->byte))
> return -EPROTO;
> diff --git a/drivers/i2c/i2c-core-base.c b/drivers/i2c/i2c-core-base.c
> index e77bab2fb467..56b42558575e 100644
> --- a/drivers/i2c/i2c-core-base.c
> +++ b/drivers/i2c/i2c-core-base.c
> @@ -2205,7 +2205,7 @@ static int i2c_detect_address(struct i2c_client *temp_client,
> dev_warn(&adapter->dev,
> "This adapter will soon drop class based instantiation of devices. "
> "Please make sure client 0x%02x gets instantiated by other means. "
> - "Check 'Documentation/i2c/instantiating-devices' for details.\n",
> + "Check 'Documentation/i2c/instantiating-devices.rst' for details.\n",
> info.addr);
>
> dev_dbg(&adapter->dev, "Creating %s at 0x%02x\n",
> @@ -2235,7 +2235,7 @@ static int i2c_detect(struct i2c_adapter *adapter, struct i2c_driver *driver)
> if (adapter->class == I2C_CLASS_DEPRECATED) {
> dev_dbg(&adapter->dev,
> "This adapter dropped support for I2C classes and won't auto-detect %s devices anymore. "
> - "If you need it, check 'Documentation/i2c/instantiating-devices' for alternatives.\n",
> + "If you need it, check 'Documentation/i2c/instantiating-devices.rst' for alternatives.\n",
> driver->driver.name);
> return 0;
> }
> diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
> index 8f99c005458a..d28974ad9e0e 100644
> --- a/drivers/iio/dummy/iio_simple_dummy.c
> +++ b/drivers/iio/dummy/iio_simple_dummy.c
> @@ -693,7 +693,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
> * Varies depending on bus type of the device. As there is no device
> * here, call probe directly. For information on device registration
> * i2c:
> - * Documentation/i2c/writing-clients
> + * Documentation/i2c/writing-clients.rst
> * spi:
> * Documentation/spi/spi-summary
> */
> diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
> index 225a8df1d4e9..1803f3cab39f 100644
> --- a/drivers/rtc/rtc-ds1374.c
> +++ b/drivers/rtc/rtc-ds1374.c
> @@ -14,7 +14,7 @@
> */
> /*
> * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
> - * recommened in .../Documentation/i2c/writing-clients section
> + * recommened in .../Documentation/i2c/writing-clients.rst section
> * "Sending and receiving", using SMBus level communication is preferred.
> */
>
> diff --git a/include/linux/i2c.h b/include/linux/i2c.h
> index fa5552c2307b..c0a78c069117 100644
> --- a/include/linux/i2c.h
> +++ b/include/linux/i2c.h
> @@ -521,7 +521,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
> *
> * The return codes from the @master_xfer{_atomic} fields should indicate the
> * type of error code that occurred during the transfer, as documented in the
> - * Kernel Documentation file Documentation/i2c/fault-codes.
> + * Kernel Documentation file Documentation/i2c/fault-codes.rst.
> */
> struct i2c_algorithm {
> /*
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 5/5] docs: spi: convert to ReST and add it to the kABI bookset
2019-06-28 21:23 ` [PATCH 5/5] docs: spi: convert to ReST and add it to the kABI bookset Mauro Carvalho Chehab
@ 2019-07-14 16:24 ` Jonathan Cameron
0 siblings, 0 replies; 14+ messages in thread
From: Jonathan Cameron @ 2019-07-14 16:24 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mark Brown, Hartmut Knaack, Lars-Peter Clausen,
Peter Meerwald-Stadler, linux-spi, linux-iio
On Fri, 28 Jun 2019 18:23:16 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> While there's one file there with briefily describes the uAPI,
> the documentation was written just like most subsystems: focused
> on kernel developers. So, add it together with driver-api books.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
For the minimal touch on IIO.
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Thanks,
> ---
> Documentation/index.rst | 1 +
> .../spi/{butterfly => butterfly.rst} | 44 ++++----
> Documentation/spi/index.rst | 23 ++++
> Documentation/spi/{pxa2xx => pxa2xx.rst} | 94 ++++++++--------
> .../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 ++-
> .../spi/{spi-sc18is602 => spi-sc18is602.rst} | 3 +
> .../spi/{spi-summary => spi-summary.rst} | 103 ++++++++++--------
> Documentation/spi/{spidev => spidev.rst} | 30 +++--
> drivers/iio/dummy/iio_simple_dummy.c | 2 +-
> drivers/spi/Kconfig | 2 +-
> drivers/spi/spi-butterfly.c | 2 +-
> drivers/spi/spi-lm70llp.c | 2 +-
> include/linux/platform_data/sc18is602.h | 2 +-
> 13 files changed, 198 insertions(+), 127 deletions(-)
> rename Documentation/spi/{butterfly => butterfly.rst} (71%)
> create mode 100644 Documentation/spi/index.rst
> rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
> rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
> rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (97%)
> rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
> rename Documentation/spi/{spidev => spidev.rst} (90%)
>
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 38ece18f5d1e..bcaddbfa817f 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -115,6 +115,7 @@ needed).
> power/index
> target/index
> timers/index
> + spi/index
> w1/index
> watchdog/index
> input/index
> diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly.rst
> similarity index 71%
> rename from Documentation/spi/butterfly
> rename to Documentation/spi/butterfly.rst
> index 9927af7a629c..e614a589547c 100644
> --- a/Documentation/spi/butterfly
> +++ b/Documentation/spi/butterfly.rst
> @@ -1,3 +1,4 @@
> +===================================================
> spi_butterfly - parport-to-butterfly adapter driver
> ===================================================
>
> @@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP"
> connector pins (used also on non-Butterfly AVR boards). On the parport
> side this is like "sp12" programming cables.
>
> + ====== ============= ===================
> Signal Butterfly Parport (DB-25)
> - ------ --------- ---------------
> - SCK = J403.PB1/SCK = pin 2/D0
> - RESET = J403.nRST = pin 3/D1
> - VCC = J403.VCC_EXT = pin 8/D6
> - MOSI = J403.PB2/MOSI = pin 9/D7
> - MISO = J403.PB3/MISO = pin 11/S7,nBUSY
> - GND = J403.GND = pin 23/GND
> + ====== ============= ===================
> + SCK J403.PB1/SCK pin 2/D0
> + RESET J403.nRST pin 3/D1
> + VCC J403.VCC_EXT pin 8/D6
> + MOSI J403.PB2/MOSI pin 9/D7
> + MISO J403.PB3/MISO pin 11/S7,nBUSY
> + GND J403.GND pin 23/GND
> + ====== ============= ===================
>
> Then to let Linux master that bus to talk to the DataFlash chip, you must
> (a) flash new firmware that disables SPI (set PRR.2, and disable pullups
> by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and
> (c) cable in the chipselect.
>
> + ====== ============ ===================
> Signal Butterfly Parport (DB-25)
> - ------ --------- ---------------
> - VCC = J400.VCC_EXT = pin 7/D5
> - SELECT = J400.PB0/nSS = pin 17/C3,nSELECT
> - GND = J400.GND = pin 24/GND
> + ====== ============ ===================
> + VCC J400.VCC_EXT pin 7/D5
> + SELECT J400.PB0/nSS pin 17/C3,nSELECT
> + GND J400.GND pin 24/GND
> + ====== ============ ===================
>
> Or you could flash firmware making the AVR into an SPI slave (keeping the
> DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
> @@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware,
> while letting either Linux or the AVR use the DataFlash. There are plenty
> of spare parport pins to wire this one up, such as:
>
> + ====== ============= ===================
> Signal Butterfly Parport (DB-25)
> - ------ --------- ---------------
> - SCK = J403.PE4/USCK = pin 5/D3
> - MOSI = J403.PE5/DI = pin 6/D4
> - MISO = J403.PE6/DO = pin 12/S5,nPAPEROUT
> - GND = J403.GND = pin 22/GND
> -
> - IRQ = J402.PF4 = pin 10/S6,ACK
> - GND = J402.GND(P2) = pin 25/GND
> + ====== ============= ===================
> + SCK J403.PE4/USCK pin 5/D3
> + MOSI J403.PE5/DI pin 6/D4
> + MISO J403.PE6/DO pin 12/S5,nPAPEROUT
> + GND J403.GND pin 22/GND
>
> + IRQ J402.PF4 pin 10/S6,ACK
> + GND J402.GND(P2) pin 25/GND
> + ====== ============= ===================
> diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
> new file mode 100644
> index 000000000000..bad6259a7bb6
> --- /dev/null
> +++ b/Documentation/spi/index.rst
> @@ -0,0 +1,23 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=================================
> +Serial Peripheral Interface (SPI)
> +=================================
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + spi-summary
> + spidev
> + butterfly
> + pxa2xx
> + spi-lm70llp
> + spi-sc18is602
> +
> +.. only:: subproject and html
> +
> + Indices
> + =======
> +
> + * :ref:`genindex`
> +
> diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx.rst
> similarity index 83%
> rename from Documentation/spi/pxa2xx
> rename to Documentation/spi/pxa2xx.rst
> index 551325b66b23..457faef8be74 100644
> --- a/Documentation/spi/pxa2xx
> +++ b/Documentation/spi/pxa2xx.rst
> @@ -1,8 +1,10 @@
> +==============================
> PXA2xx SPI on SSP driver HOWTO
> -===================================================
> +==============================
> +
> This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx
> synchronous serial port into a SPI master controller
> -(see Documentation/spi/spi-summary). The driver has the following features
> +(see Documentation/spi/spi-summary.rst). The driver has the following features
>
> - Support for any PXA2xx SSP
> - SSP PIO and SSP DMA data transfers.
> @@ -19,12 +21,12 @@ Declaring PXA2xx Master Controllers
> -----------------------------------
> Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a
> "platform device". The master configuration is passed to the driver via a table
> -found in include/linux/spi/pxa2xx_spi.h:
> +found in include/linux/spi/pxa2xx_spi.h::
>
> -struct pxa2xx_spi_controller {
> + struct pxa2xx_spi_controller {
> u16 num_chipselect;
> u8 enable_dma;
> -};
> + };
>
> The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
> slave device (chips) attached to this SPI master.
> @@ -36,9 +38,9 @@ See the "PXA2xx Developer Manual" section "DMA Controller".
>
> NSSP MASTER SAMPLE
> ------------------
> -Below is a sample configuration using the PXA255 NSSP.
> +Below is a sample configuration using the PXA255 NSSP::
>
> -static struct resource pxa_spi_nssp_resources[] = {
> + static struct resource pxa_spi_nssp_resources[] = {
> [0] = {
> .start = __PREG(SSCR0_P(2)), /* Start address of NSSP */
> .end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
> @@ -49,14 +51,14 @@ static struct resource pxa_spi_nssp_resources[] = {
> .end = IRQ_NSSP,
> .flags = IORESOURCE_IRQ,
> },
> -};
> + };
>
> -static struct pxa2xx_spi_controller pxa_nssp_master_info = {
> + static struct pxa2xx_spi_controller pxa_nssp_master_info = {
> .num_chipselect = 1, /* Matches the number of chips attached to NSSP */
> .enable_dma = 1, /* Enables NSSP DMA */
> -};
> + };
>
> -static struct platform_device pxa_spi_nssp = {
> + static struct platform_device pxa_spi_nssp = {
> .name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
> .id = 2, /* Bus number, MUST MATCH SSP number 1..n */
> .resource = pxa_spi_nssp_resources,
> @@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = {
> .dev = {
> .platform_data = &pxa_nssp_master_info, /* Passed to driver */
> },
> -};
> + };
>
> -static struct platform_device *devices[] __initdata = {
> + static struct platform_device *devices[] __initdata = {
> &pxa_spi_nssp,
> -};
> + };
>
> -static void __init board_init(void)
> -{
> + static void __init board_init(void)
> + {
> (void)platform_add_device(devices, ARRAY_SIZE(devices));
> -}
> + }
>
> Declaring Slave Devices
> -----------------------
> Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
> using the "spi_board_info" structure found in "linux/spi/spi.h". See
> -"Documentation/spi/spi-summary" for additional information.
> +"Documentation/spi/spi-summary.rst" for additional information.
>
> Each slave device attached to the PXA must provide slave specific configuration
> information via the structure "pxa2xx_spi_chip" found in
> @@ -87,19 +89,21 @@ information via the structure "pxa2xx_spi_chip" found in
> will uses the configuration whenever the driver communicates with the slave
> device. All fields are optional.
>
> -struct pxa2xx_spi_chip {
> +::
> +
> + struct pxa2xx_spi_chip {
> u8 tx_threshold;
> u8 rx_threshold;
> u8 dma_burst_size;
> u32 timeout;
> u8 enable_loopback;
> void (*cs_control)(u32 command);
> -};
> + };
>
> The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
> used to configure the SSP hardware fifo. These fields are critical to the
> performance of pxa2xx_spi driver and misconfiguration will result in rx
> -fifo overruns (especially in PIO mode transfers). Good default values are
> +fifo overruns (especially in PIO mode transfers). Good default values are::
>
> .tx_threshold = 8,
> .rx_threshold = 8,
> @@ -141,41 +145,43 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
> "spi_board_info.controller_data" field. Below is a sample configuration using
> the PXA255 NSSP.
>
> -/* Chip Select control for the CS8415A SPI slave device */
> -static void cs8415a_cs_control(u32 command)
> -{
> +::
> +
> + /* Chip Select control for the CS8415A SPI slave device */
> + static void cs8415a_cs_control(u32 command)
> + {
> if (command & PXA2XX_CS_ASSERT)
> GPCR(2) = GPIO_bit(2);
> else
> GPSR(2) = GPIO_bit(2);
> -}
> + }
>
> -/* Chip Select control for the CS8405A SPI slave device */
> -static void cs8405a_cs_control(u32 command)
> -{
> + /* Chip Select control for the CS8405A SPI slave device */
> + static void cs8405a_cs_control(u32 command)
> + {
> if (command & PXA2XX_CS_ASSERT)
> GPCR(3) = GPIO_bit(3);
> else
> GPSR(3) = GPIO_bit(3);
> -}
> + }
>
> -static struct pxa2xx_spi_chip cs8415a_chip_info = {
> + static struct pxa2xx_spi_chip cs8415a_chip_info = {
> .tx_threshold = 8, /* SSP hardward FIFO threshold */
> .rx_threshold = 8, /* SSP hardward FIFO threshold */
> .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
> .timeout = 235, /* See Intel documentation */
> .cs_control = cs8415a_cs_control, /* Use external chip select */
> -};
> + };
>
> -static struct pxa2xx_spi_chip cs8405a_chip_info = {
> + static struct pxa2xx_spi_chip cs8405a_chip_info = {
> .tx_threshold = 8, /* SSP hardward FIFO threshold */
> .rx_threshold = 8, /* SSP hardward FIFO threshold */
> .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
> .timeout = 235, /* See Intel documentation */
> .cs_control = cs8405a_cs_control, /* Use external chip select */
> -};
> + };
>
> -static struct spi_board_info streetracer_spi_board_info[] __initdata = {
> + static struct spi_board_info streetracer_spi_board_info[] __initdata = {
> {
> .modalias = "cs8415a", /* Name of spi_driver for this device */
> .max_speed_hz = 3686400, /* Run SSP as fast a possbile */
> @@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
> .controller_data = &cs8405a_chip_info, /* Master chip config */
> .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
> },
> -};
> + };
>
> -static void __init streetracer_init(void)
> -{
> + static void __init streetracer_init(void)
> + {
> spi_register_board_info(streetracer_spi_board_info,
> ARRAY_SIZE(streetracer_spi_board_info));
> -}
> + }
>
>
> DMA and PIO I/O Support
> @@ -210,22 +216,22 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The
> mode supports both coherent and stream based DMA mappings.
>
> The following logic is used to determine the type of I/O to be used on
> -a per "spi_transfer" basis:
> +a per "spi_transfer" basis::
>
> -if !enable_dma then
> + if !enable_dma then
> always use PIO transfers
>
> -if spi_message.len > 8191 then
> + if spi_message.len > 8191 then
> print "rate limited" warning
> use PIO transfers
>
> -if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
> + if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
> use coherent DMA mode
>
> -if rx_buf and tx_buf are aligned on 8 byte boundary then
> + if rx_buf and tx_buf are aligned on 8 byte boundary then
> use streaming DMA mode
>
> -otherwise
> + otherwise
> use PIO transfer
>
> THANKS TO
> diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp.rst
> similarity index 88%
> rename from Documentation/spi/spi-lm70llp
> rename to Documentation/spi/spi-lm70llp.rst
> index 463f6d01fa15..07631aef4343 100644
> --- a/Documentation/spi/spi-lm70llp
> +++ b/Documentation/spi/spi-lm70llp.rst
> @@ -1,8 +1,11 @@
> +==============================================
> spi_lm70llp : LM70-LLP parport-to-SPI adapter
> ==============================================
>
> Supported board/chip:
> +
> * National Semiconductor LM70 LLP evaluation board
> +
> Datasheet: http://www.national.com/pf/LM/LM70.html
>
> Author:
> @@ -29,9 +32,10 @@ available (on page 4) here:
>
> The hardware interfacing on the LM70 LLP eval board is as follows:
>
> + ======== == ========= ==========
> Parallel LM70 LLP
> - Port Direction JP2 Header
> - ----------- --------- ----------------
> + Port . Direction JP2 Header
> + ======== == ========= ==========
> D0 2 - -
> D1 3 --> V+ 5
> D2 4 --> V+ 5
> @@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows:
> D7 9 --> SI/O 5
> GND 25 - GND 7
> Select 13 <-- SI/O 1
> - ----------- --------- ----------------
> + ======== == ========= ==========
>
> Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
> is connected to both pin D7 (as Master Out) and Select (as Master In)
> @@ -74,6 +78,7 @@ inverting the value read at pin 13.
>
> Thanks to
> ---------
> -o David Brownell for mentoring the SPI-side driver development.
> -o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
> -o Nadir Billimoria for help interpreting the circuit schematic.
> +
> +- David Brownell for mentoring the SPI-side driver development.
> +- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
> +- Nadir Billimoria for help interpreting the circuit schematic.
> diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602.rst
> similarity index 97%
> rename from Documentation/spi/spi-sc18is602
> rename to Documentation/spi/spi-sc18is602.rst
> index 0feffd5af411..2a31dc722321 100644
> --- a/Documentation/spi/spi-sc18is602
> +++ b/Documentation/spi/spi-sc18is602.rst
> @@ -1,8 +1,11 @@
> +===========================
> Kernel driver spi-sc18is602
> ===========================
>
> Supported chips:
> +
> * NXP SI18IS602/602B/603
> +
> Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
>
> Author:
> diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary.rst
> similarity index 93%
> rename from Documentation/spi/spi-summary
> rename to Documentation/spi/spi-summary.rst
> index 1a63194b74d7..96b3f8b8b3db 100644
> --- a/Documentation/spi/spi-summary
> +++ b/Documentation/spi/spi-summary.rst
> @@ -1,3 +1,4 @@
> +====================================
> Overview of Linux kernel SPI support
> ====================================
>
> @@ -139,12 +140,14 @@ a command and then reading its response.
>
> There are two types of SPI driver, here called:
>
> - Controller drivers ... controllers may be built into System-On-Chip
> + Controller drivers ...
> + controllers may be built into System-On-Chip
> processors, and often support both Master and Slave roles.
> These drivers touch hardware registers and may use DMA.
> Or they can be PIO bitbangers, needing just GPIO pins.
>
> - Protocol drivers ... these pass messages through the controller
> + Protocol drivers ...
> + these pass messages through the controller
> driver to communicate with a Slave or Master device on the
> other side of an SPI link.
>
> @@ -160,7 +163,7 @@ those two types of drivers.
> There is a minimal core of SPI programming interfaces, focussing on
> using the driver model to connect controller and protocol drivers using
> device tables provided by board specific initialization code. SPI
> -shows up in sysfs in several locations:
> +shows up in sysfs in several locations::
>
> /sys/devices/.../CTLR ... physical node for a given SPI controller
>
> @@ -206,7 +209,8 @@ Linux needs several kinds of information to properly configure SPI devices.
> That information is normally provided by board-specific code, even for
> chips that do support some of automated discovery/enumeration.
>
> -DECLARE CONTROLLERS
> +Declare Controllers
> +^^^^^^^^^^^^^^^^^^^
>
> The first kind of information is a list of what SPI controllers exist.
> For System-on-Chip (SOC) based boards, these will usually be platform
> @@ -221,7 +225,7 @@ same basic controller setup code. This is because most SOCs have several
> SPI-capable controllers, and only the ones actually usable on a given
> board should normally be set up and registered.
>
> -So for example arch/.../mach-*/board-*.c files might have code like:
> +So for example arch/.../mach-*/board-*.c files might have code like::
>
> #include <mach/spi.h> /* for mysoc_spi_data */
>
> @@ -238,7 +242,7 @@ So for example arch/.../mach-*/board-*.c files might have code like:
> ...
> }
>
> -And SOC-specific utility code might look something like:
> +And SOC-specific utility code might look something like::
>
> #include <mach/spi.h>
>
> @@ -269,8 +273,8 @@ same SOC controller is used. For example, on one board SPI might use
> an external clock, where another derives the SPI clock from current
> settings of some master clock.
>
> -
> -DECLARE SLAVE DEVICES
> +Declare Slave Devices
> +^^^^^^^^^^^^^^^^^^^^^
>
> The second kind of information is a list of what SPI slave devices exist
> on the target board, often with some board-specific data needed for the
> @@ -278,7 +282,7 @@ driver to work correctly.
>
> Normally your arch/.../mach-*/board-*.c files would provide a small table
> listing the SPI devices on each board. (This would typically be only a
> -small handful.) That might look like:
> +small handful.) That might look like::
>
> static struct ads7846_platform_data ads_info = {
> .vref_delay_usecs = 100,
> @@ -316,7 +320,7 @@ not possible until the infrastructure knows how to deselect it.
>
> Then your board initialization code would register that table with the SPI
> infrastructure, so that it's available later when the SPI master controller
> -driver is registered:
> +driver is registered::
>
> spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
>
> @@ -324,12 +328,13 @@ Like with other static board-specific setup, you won't unregister those.
>
> The widely used "card" style computers bundle memory, cpu, and little else
> onto a card that's maybe just thirty square centimeters. On such systems,
> -your arch/.../mach-.../board-*.c file would primarily provide information
> +your ``arch/.../mach-.../board-*.c`` file would primarily provide information
> about the devices on the mainboard into which such a card is plugged. That
> certainly includes SPI devices hooked up through the card connectors!
>
>
> -NON-STATIC CONFIGURATIONS
> +Non-static Configurations
> +^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Developer boards often play by different rules than product boards, and one
> example is the potential need to hotplug SPI devices and/or controllers.
> @@ -349,7 +354,7 @@ How do I write an "SPI Protocol Driver"?
> Most SPI drivers are currently kernel drivers, but there's also support
> for userspace drivers. Here we talk only about kernel drivers.
>
> -SPI protocol drivers somewhat resemble platform device drivers:
> +SPI protocol drivers somewhat resemble platform device drivers::
>
> static struct spi_driver CHIP_driver = {
> .driver = {
> @@ -367,6 +372,8 @@ device whose board_info gave a modalias of "CHIP". Your probe() code
> might look like this unless you're creating a device which is managing
> a bus (appearing under /sys/class/spi_master).
>
> +::
> +
> static int CHIP_probe(struct spi_device *spi)
> {
> struct CHIP *chip;
> @@ -479,6 +486,8 @@ The main task of this type of driver is to provide an "spi_master".
> Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
> to get the driver-private data allocated for that device.
>
> +::
> +
> struct spi_master *master;
> struct CONTROLLER *c;
>
> @@ -503,7 +512,8 @@ If you need to remove your SPI controller driver, spi_unregister_master()
> will reverse the effect of spi_register_master().
>
>
> -BUS NUMBERING
> +Bus Numbering
> +^^^^^^^^^^^^^
>
> Bus numbering is important, since that's how Linux identifies a given
> SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
> @@ -517,9 +527,10 @@ then be replaced by a dynamically assigned number. You'd then need to treat
> this as a non-static configuration (see above).
>
>
> -SPI MASTER METHODS
> +SPI Master Methods
> +^^^^^^^^^^^^^^^^^^
>
> - master->setup(struct spi_device *spi)
> +``master->setup(struct spi_device *spi)``
> This sets up the device clock rate, SPI mode, and word sizes.
> Drivers may change the defaults provided by board_info, and then
> call spi_setup(spi) to invoke this routine. It may sleep.
> @@ -528,37 +539,37 @@ SPI MASTER METHODS
> change them right away ... otherwise drivers could corrupt I/O
> that's in progress for other SPI devices.
>
> - ** BUG ALERT: for some reason the first version of
> - ** many spi_master drivers seems to get this wrong.
> - ** When you code setup(), ASSUME that the controller
> - ** is actively processing transfers for another device.
> + .. note::
>
> - master->cleanup(struct spi_device *spi)
> + BUG ALERT: for some reason the first version of
> + many spi_master drivers seems to get this wrong.
> + When you code setup(), ASSUME that the controller
> + is actively processing transfers for another device.
> +
> +``master->cleanup(struct spi_device *spi)``
> Your controller driver may use spi_device.controller_state to hold
> state it dynamically associates with that device. If you do that,
> be sure to provide the cleanup() method to free that state.
>
> - master->prepare_transfer_hardware(struct spi_master *master)
> +``master->prepare_transfer_hardware(struct spi_master *master)``
> This will be called by the queue mechanism to signal to the driver
> that a message is coming in soon, so the subsystem requests the
> driver to prepare the transfer hardware by issuing this call.
> This may sleep.
>
> - master->unprepare_transfer_hardware(struct spi_master *master)
> +``master->unprepare_transfer_hardware(struct spi_master *master)``
> This will be called by the queue mechanism to signal to the driver
> that there are no more messages pending in the queue and it may
> relax the hardware (e.g. by power management calls). This may sleep.
>
> - master->transfer_one_message(struct spi_master *master,
> - struct spi_message *mesg)
> +``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
> The subsystem calls the driver to transfer a single message while
> queuing transfers that arrive in the meantime. When the driver is
> finished with this message, it must call
> spi_finalize_current_message() so the subsystem can issue the next
> message. This may sleep.
>
> - master->transfer_one(struct spi_master *master, struct spi_device *spi,
> - struct spi_transfer *transfer)
> +``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
> The subsystem calls the driver to transfer a single transfer while
> queuing transfers that arrive in the meantime. When the driver is
> finished with this transfer, it must call
> @@ -568,19 +579,20 @@ SPI MASTER METHODS
> not call your transfer_one callback.
>
> Return values:
> - negative errno: error
> - 0: transfer is finished
> - 1: transfer is still in progress
>
> - master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles,
> - u8 hold_clk_cycles, u8 inactive_clk_cycles)
> + * negative errno: error
> + * 0: transfer is finished
> + * 1: transfer is still in progress
> +
> +``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
> This method allows SPI client drivers to request SPI master controller
> for configuring device specific CS setup, hold and inactive timing
> requirements.
>
> - DEPRECATED METHODS
> +Deprecated Methods
> +^^^^^^^^^^^^^^^^^^
>
> - master->transfer(struct spi_device *spi, struct spi_message *message)
> +``master->transfer(struct spi_device *spi, struct spi_message *message)``
> This must not sleep. Its responsibility is to arrange that the
> transfer happens and its complete() callback is issued. The two
> will normally happen later, after other transfers complete, and
> @@ -590,7 +602,8 @@ SPI MASTER METHODS
> implemented.
>
>
> -SPI MESSAGE QUEUE
> +SPI Message Queue
> +^^^^^^^^^^^^^^^^^
>
> If you are happy with the standard queueing mechanism provided by the
> SPI subsystem, just implement the queued methods specified above. Using
> @@ -619,13 +632,13 @@ THANKS TO
> Contributors to Linux-SPI discussions include (in alphabetical order,
> by last name):
>
> -Mark Brown
> -David Brownell
> -Russell King
> -Grant Likely
> -Dmitry Pervushin
> -Stephen Street
> -Mark Underwood
> -Andrew Victor
> -Linus Walleij
> -Vitaly Wool
> +- Mark Brown
> +- David Brownell
> +- Russell King
> +- Grant Likely
> +- Dmitry Pervushin
> +- Stephen Street
> +- Mark Underwood
> +- Andrew Victor
> +- Linus Walleij
> +- Vitaly Wool
> diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev.rst
> similarity index 90%
> rename from Documentation/spi/spidev
> rename to Documentation/spi/spidev.rst
> index 3d14035b1766..f05dbc5ccdbc 100644
> --- a/Documentation/spi/spidev
> +++ b/Documentation/spi/spidev.rst
> @@ -1,7 +1,13 @@
> +=================
> +SPI userspace API
> +=================
> +
> SPI devices have a limited userspace API, supporting basic half-duplex
> read() and write() access to SPI slave devices. Using ioctl() requests,
> full duplex transfers and device I/O configuration are also available.
>
> +::
> +
> #include <fcntl.h>
> #include <unistd.h>
> #include <sys/ioctl.h>
> @@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev.
> busybox; it's less featureful, but often enough.) For a SPI device with
> chipselect C on bus B, you should see:
>
> - /dev/spidevB.C ... character special device, major number 153 with
> + /dev/spidevB.C ...
> + character special device, major number 153 with
> a dynamically chosen minor device number. This is the node
> that userspace programs will open, created by "udev" or "mdev".
>
> - /sys/devices/.../spiB.C ... as usual, the SPI device node will
> + /sys/devices/.../spiB.C ...
> + as usual, the SPI device node will
> be a child of its SPI master controller.
>
> - /sys/class/spidev/spidevB.C ... created when the "spidev" driver
> + /sys/class/spidev/spidevB.C ...
> + created when the "spidev" driver
> binds to that device. (Directory or symlink, based on whether
> or not you enabled the "deprecated sysfs files" Kconfig option.)
>
> @@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request.
> Several ioctl() requests let your driver read or override the device's current
> settings for data transfer parameters:
>
> - SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
> + SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
> + pass a pointer to a byte which will
> return (RD) or assign (WR) the SPI transfer mode. Use the constants
> SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
> (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
> @@ -88,22 +98,26 @@ settings for data transfer parameters:
> Note that this request is limited to SPI mode flags that fit in a
> single byte.
>
> - SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
> + SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
> + pass a pointer to a uin32_t
> which will return (RD) or assign (WR) the full SPI transfer mode,
> not limited to the bits that fit in one byte.
>
> - SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
> + SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
> + pass a pointer to a byte
> which will return (RD) or assign (WR) the bit justification used to
> transfer SPI words. Zero indicates MSB-first; other values indicate
> the less common LSB-first encoding. In both cases the specified value
> is right-justified in each word, so that unused (TX) or undefined (RX)
> bits are in the MSBs.
>
> - SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
> + SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
> + pass a pointer to
> a byte which will return (RD) or assign (WR) the number of bits in
> each SPI transfer word. The value zero signifies eight bits.
>
> - SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
> + SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
> + pass a pointer to a
> u32 which will return (RD) or assign (WR) the maximum SPI transfer
> speed, in Hz. The controller can't necessarily assign that specific
> clock speed.
> diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
> index d28974ad9e0e..6cb02299a215 100644
> --- a/drivers/iio/dummy/iio_simple_dummy.c
> +++ b/drivers/iio/dummy/iio_simple_dummy.c
> @@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
> * i2c:
> * Documentation/i2c/writing-clients.rst
> * spi:
> - * Documentation/spi/spi-summary
> + * Documentation/spi/spi-summary.rst
> */
> static const struct iio_sw_device_ops iio_dummy_device_ops = {
> .probe = iio_dummy_probe,
> diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig
> index 3a1d8f1170de..d5a24fe983e7 100644
> --- a/drivers/spi/Kconfig
> +++ b/drivers/spi/Kconfig
> @@ -543,7 +543,7 @@ config SPI_PXA2XX
> help
> This enables using a PXA2xx or Sodaville SSP port as a SPI master
> controller. The driver can be configured to use any SSP port and
> - additional documentation can be found a Documentation/spi/pxa2xx.
> + additional documentation can be found a Documentation/spi/pxa2xx.rst.
>
> config SPI_PXA2XX_PCI
> def_tristate SPI_PXA2XX && PCI && COMMON_CLK
> diff --git a/drivers/spi/spi-butterfly.c b/drivers/spi/spi-butterfly.c
> index 8c77d1114ad3..7e71a351f3b7 100644
> --- a/drivers/spi/spi-butterfly.c
> +++ b/drivers/spi/spi-butterfly.c
> @@ -23,7 +23,7 @@
> * with a battery powered AVR microcontroller and lots of goodies. You
> * can use GCC to develop firmware for this.
> *
> - * See Documentation/spi/butterfly for information about how to build
> + * See Documentation/spi/butterfly.rst for information about how to build
> * and use this custom parallel port cable.
> */
>
> diff --git a/drivers/spi/spi-lm70llp.c b/drivers/spi/spi-lm70llp.c
> index f18f912c9dea..174dba29b1dd 100644
> --- a/drivers/spi/spi-lm70llp.c
> +++ b/drivers/spi/spi-lm70llp.c
> @@ -34,7 +34,7 @@
> * available (on page 4) here:
> * http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
> *
> - * Also see Documentation/spi/spi-lm70llp. The SPI<->parport code here is
> + * Also see Documentation/spi/spi-lm70llp.rst. The SPI<->parport code here is
> * (heavily) based on spi-butterfly by David Brownell.
> *
> * The LM70 LLP connects to the PC parallel port in the following manner:
> diff --git a/include/linux/platform_data/sc18is602.h b/include/linux/platform_data/sc18is602.h
> index e066d3b0d6d8..0e91489edfe6 100644
> --- a/include/linux/platform_data/sc18is602.h
> +++ b/include/linux/platform_data/sc18is602.h
> @@ -4,7 +4,7 @@
> *
> * Copyright (C) 2012 Guenter Roeck <linux@roeck-us.net>
> *
> - * For further information, see the Documentation/spi/spi-sc18is602 file.
> + * For further information, see the Documentation/spi/spi-sc18is602.rst file.
> */
>
> /**
^ permalink raw reply [flat|nested] 14+ messages in thread
end of thread, other threads:[~2019-07-14 16:25 UTC | newest]
Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-06-28 21:23 [PATCH 0/5] Convert misc-devices, i2c, w1, spi and some markdown files to ReST Mauro Carvalho Chehab
2019-06-28 21:23 ` [PATCH 1/5] docs: convert markdown documents " Mauro Carvalho Chehab
2019-06-28 22:38 ` Rob Herring
2019-06-28 21:23 ` [PATCH 2/5] docs: misc-devices: convert files without extension " Mauro Carvalho Chehab
2019-06-28 21:23 ` [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset Mauro Carvalho Chehab
2019-06-28 21:41 ` Alexandre Belloni
2019-06-28 21:54 ` Mauro Carvalho Chehab
2019-06-28 22:10 ` Alexandre Belloni
2019-06-29 10:57 ` Wolfram Sang
2019-06-29 11:37 ` Alexandre Belloni
2019-07-14 16:23 ` Jonathan Cameron
2019-06-28 21:23 ` [PATCH 4/5] docs: w1: convert to ReST and add to the kAPI group of docs Mauro Carvalho Chehab
2019-06-28 21:23 ` [PATCH 5/5] docs: spi: convert to ReST and add it to the kABI bookset Mauro Carvalho Chehab
2019-07-14 16:24 ` Jonathan Cameron
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).