summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2018-02-04 21:57:43 +0300
committerLinus Torvalds <torvalds@linux-foundation.org>2018-02-04 21:57:43 +0300
commit4141cf676b9e345d3ddeb1710dd3156a09c50244 (patch)
tree4b2b6249e99efdd47eafa5780f106d593f64708b /Documentation
parent3462ac57033e79a87dbae2497773f22b9c536fbc (diff)
parente38c85644e11c6dc5a39305c96b617f63403423d (diff)
downloadlinux-4141cf676b9e345d3ddeb1710dd3156a09c50244.tar.xz
Merge branch 'i2c/for-4.16' of git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux
Pull i2c updates from Wolfram Sang: "I2C has the following changes for you: - new flag to mark DMA safe buffers in i2c_msg. Also, some infrastructure around it. And docs. - huge refactoring of the at24 driver led by the new maintainer Bartosz - update I2C bus recovery to send STOP after recovery - conversion from gpio to gpiod for I2C bus recovery - adding a fault-injector to the i2c-gpio driver - lots of small driver improvements, and bigger ones to i2c-sh_mobile" * 'i2c/for-4.16' of git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux: (99 commits) i2c: mv64xxx: Add myself as maintainer for this driver i2c: mv64xxx: Fix clock resource by adding an optional bus clock i2c: mv64xxx: Remove useless test before clk_disable_unprepare i2c: mxs: use true and false for boolean values i2c: meson: update doc description to fix build warnings i2c: meson: add configurable divider factors dt-bindings: i2c: update documentation for the Meson-AXG i2c: imx-lpi2c: add runtime pm support i2c: rcar: fix some trivial typos in comments i2c: davinci: fix the cpufreq transition i2c: rk3x: add proper kerneldoc header i2c: rk3x: account for const type of of_device_id.data i2c: acorn: remove outdated path from file header i2c: acorn: add MODULE_LICENSE tag i2c: rcar: implement bus recovery i2c: send STOP after successful bus recovery i2c: ensure SDA is released in recovery if SDA is controllable i2c: add 'set_sda' to bus_recovery_info i2c: add identifier in declarations for i2c_bus_recovery i2c: make kerneldoc about bus recovery more precise ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/devicetree/bindings/eeprom/at24.txt78
-rw-r--r--Documentation/devicetree/bindings/eeprom/eeprom.txt47
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-meson.txt6
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mtk.txt1
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt13
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt20
-rw-r--r--Documentation/i2c/DMA-considerations67
-rw-r--r--Documentation/i2c/gpio-fault-injection54
8 files changed, 236 insertions, 50 deletions
diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt
new file mode 100644
index 000000000000..1812c848e369
--- /dev/null
+++ b/Documentation/devicetree/bindings/eeprom/at24.txt
@@ -0,0 +1,78 @@
+EEPROMs (I2C)
+
+Required properties:
+
+ - compatible: Must be a "<manufacturer>,<model>" pair. The following <model>
+ values are supported (assuming "atmel" as manufacturer):
+
+ "atmel,24c00",
+ "atmel,24c01",
+ "atmel,24cs01",
+ "atmel,24c02",
+ "atmel,24cs02",
+ "atmel,24mac402",
+ "atmel,24mac602",
+ "atmel,spd",
+ "atmel,24c04",
+ "atmel,24cs04",
+ "atmel,24c08",
+ "atmel,24cs08",
+ "atmel,24c16",
+ "atmel,24cs16",
+ "atmel,24c32",
+ "atmel,24cs32",
+ "atmel,24c64",
+ "atmel,24cs64",
+ "atmel,24c128",
+ "atmel,24c256",
+ "atmel,24c512",
+ "atmel,24c1024",
+
+ If <manufacturer> is not "atmel", then a fallback must be used
+ with the same <model> and "atmel" as manufacturer.
+
+ Example:
+ compatible = "microchip,24c128", "atmel,24c128";
+
+ Supported manufacturers are:
+
+ "catalyst",
+ "microchip",
+ "ramtron",
+ "renesas",
+ "nxp",
+ "st",
+
+ Some vendors use different model names for chips which are just
+ variants of the above. Known such exceptions are listed below:
+
+ "renesas,r1ex24002" - the fallback is "atmel,24c02"
+
+ - reg: The I2C address of the EEPROM.
+
+Optional properties:
+
+ - pagesize: The length of the pagesize for writing. Please consult the
+ manual of your device, that value varies a lot. A wrong value
+ may result in data loss! If not specified, a safety value of
+ '1' is used which will be very slow.
+
+ - read-only: This parameterless property disables writes to the eeprom.
+
+ - size: Total eeprom size in bytes.
+
+ - no-read-rollover: This parameterless property indicates that the
+ multi-address eeprom does not automatically roll over
+ reads to the next slave address. Please consult the
+ manual of your device.
+
+ - wp-gpios: GPIO to which the write-protect pin of the chip is connected.
+
+Example:
+
+eeprom@52 {
+ compatible = "atmel,24c32";
+ reg = <0x52>;
+ pagesize = <32>;
+ wp-gpios = <&gpio1 3 0>;
+};
diff --git a/Documentation/devicetree/bindings/eeprom/eeprom.txt b/Documentation/devicetree/bindings/eeprom/eeprom.txt
deleted file mode 100644
index 27f2bc15298a..000000000000
--- a/Documentation/devicetree/bindings/eeprom/eeprom.txt
+++ /dev/null
@@ -1,47 +0,0 @@
-EEPROMs (I2C)
-
-Required properties:
-
- - compatible : should be "<manufacturer>,<type>", like these:
-
- "atmel,24c00", "atmel,24c01", "atmel,24c02", "atmel,24c04",
- "atmel,24c08", "atmel,24c16", "atmel,24c32", "atmel,24c64",
- "atmel,24c128", "atmel,24c256", "atmel,24c512", "atmel,24c1024"
-
- "catalyst,24c32"
-
- "microchip,24c128"
-
- "ramtron,24c64"
-
- "renesas,r1ex24002"
-
- The following manufacturers values have been deprecated:
- "at", "at24"
-
- If there is no specific driver for <manufacturer>, a generic
- device with <type> and manufacturer "atmel" should be used.
- Possible types are:
- "24c00", "24c01", "24c02", "24c04", "24c08", "24c16", "24c32", "24c64",
- "24c128", "24c256", "24c512", "24c1024", "spd"
-
- - reg : the I2C address of the EEPROM
-
-Optional properties:
-
- - pagesize : the length of the pagesize for writing. Please consult the
- manual of your device, that value varies a lot. A wrong value
- may result in data loss! If not specified, a safety value of
- '1' is used which will be very slow.
-
- - read-only: this parameterless property disables writes to the eeprom
-
- - size: total eeprom size in bytes
-
-Example:
-
-eeprom@52 {
- compatible = "atmel,24c32";
- reg = <0x52>;
- pagesize = <32>;
-};
diff --git a/Documentation/devicetree/bindings/i2c/i2c-meson.txt b/Documentation/devicetree/bindings/i2c/i2c-meson.txt
index 611b934c7e10..13d410de077c 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-meson.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-meson.txt
@@ -1,7 +1,11 @@
Amlogic Meson I2C controller
Required properties:
- - compatible: must be "amlogic,meson6-i2c" or "amlogic,meson-gxbb-i2c"
+ - compatible: must be:
+ "amlogic,meson6-i2c" for Meson8 and compatible SoCs
+ "amlogic,meson-gxbb-i2c" for GXBB and compatible SoCs
+ "amlogic,meson-axg-i2c"for AXG and compatible SoCs
+
- reg: physical address and length of the device registers
- interrupts: a single interrupt specifier
- clocks: clock for the device
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mtk.txt b/Documentation/devicetree/bindings/i2c/i2c-mtk.txt
index ff7bf37deb43..e199695b1c96 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mtk.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-mtk.txt
@@ -5,6 +5,7 @@ The MediaTek's I2C controller is used to interface with I2C devices.
Required properties:
- compatible: value should be either of the following.
"mediatek,mt2701-i2c", "mediatek,mt6577-i2c": for MediaTek MT2701
+ "mediatek,mt2712-i2c": for MediaTek MT2712
"mediatek,mt6577-i2c": for MediaTek MT6577
"mediatek,mt6589-i2c": for MediaTek MT6589
"mediatek,mt7622-i2c": for MediaTek MT7622
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt
index aa097045a10e..34d91501342e 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt
@@ -1,10 +1,19 @@
* NXP PCA954x I2C bus switch
+The driver supports NXP PCA954x and PCA984x I2C mux/switch devices.
+
Required Properties:
- compatible: Must contain one of the following.
- "nxp,pca9540", "nxp,pca9542", "nxp,pca9543", "nxp,pca9544",
- "nxp,pca9545", "nxp,pca9546", "nxp,pca9547", "nxp,pca9548"
+ "nxp,pca9540",
+ "nxp,pca9542",
+ "nxp,pca9543",
+ "nxp,pca9544",
+ "nxp,pca9545",
+ "nxp,pca9546", "nxp,pca9846",
+ "nxp,pca9547", "nxp,pca9847",
+ "nxp,pca9548", "nxp,pca9848",
+ "nxp,pca9849"
- reg: The I2C address of the device.
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt b/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt
index 5c30026921ae..0ffe65a316ae 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt
@@ -25,6 +25,15 @@ default frequency is 100kHz
whenever you're using the "allwinner,sun6i-a31-i2c"
compatible.
+ - clocks: : pointers to the reference clocks for this device, the
+ first one is the one used for the clock on the i2c bus,
+ the second one is the clock used to acces the registers
+ of the controller
+
+ - clock-names : names of used clocks, mandatory if the second clock is
+ used, the name must be "core", and "reg" (the latter is
+ only for Armada 7K/8K).
+
Examples:
i2c@11000 {
@@ -42,3 +51,14 @@ For the Armada XP:
interrupts = <29>;
clock-frequency = <100000>;
};
+
+For the Armada 7040:
+
+ i2c@701000 {
+ compatible = "marvell,mv78230-i2c";
+ reg = <0x701000 0x20>;
+ interrupts = <29>;
+ clock-frequency = <100000>;
+ clock-names = "core", "reg";
+ clocks = <&core_clock>, <&reg_clock>;
+ };
diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/DMA-considerations
new file mode 100644
index 000000000000..966610aa4620
--- /dev/null
+++ b/Documentation/i2c/DMA-considerations
@@ -0,0 +1,67 @@
+=================
+Linux I2C and DMA
+=================
+
+Given that i2c is a low-speed bus, over which the majority of messages
+transferred are small, it is not considered a prime user of DMA access. At this
+time of writing, only 10% of I2C bus master drivers have DMA support
+implemented. And the vast majority of transactions are so small that setting up
+DMA for it will likely add more overhead than a plain PIO transfer.
+
+Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe.
+It does not seem reasonable to apply additional burdens when the feature is so
+rarely used. However, it is recommended to use a DMA-safe buffer if your
+message size is likely applicable for DMA. Most drivers have this threshold
+around 8 bytes (as of today, this is mostly an educated guess, however). For
+any message of 16 byte or larger, it is probably a really good idea. Please
+note that other subsystems you use might add requirements. E.g., if your
+I2C bus master driver is using USB as a bridge, then you need to have DMA
+safe buffers always, because USB requires it.
+
+Clients
+-------
+
+For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE
+flag with it. Then, the I2C core and drivers know they can safely operate DMA
+on it. Note that using this flag is optional. I2C host drivers which are not
+updated to use this flag will work like before. And like before, they risk
+using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in
+more and more clients and host drivers is the planned way forward. Note also
+that setting this flag makes only sense in kernel space. User space data is
+copied into kernel space anyhow. The I2C core makes sure the destination
+buffers in kernel space are always DMA capable. Also, when the core emulates
+SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users
+of i2c_master_send() and i2c_master_recv() functions can now use DMA safe
+variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they
+know their buffers are DMA safe. Users of i2c_transfer() must set the
+I2C_M_DMA_SAFE flag manually.
+
+Masters
+-------
+
+Bus master drivers wishing to implement safe DMA can use helper functions from
+the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a
+certain threshold is met::
+
+ dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte);
+
+If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a
+bounce buffer. But you don't need to care about that detail, just use the
+returned buffer. If NULL is returned, the threshold was not met or a bounce
+buffer could not be allocated. Fall back to PIO in that case.
+
+In any case, a buffer obtained from above needs to be released. It ensures data
+is copied back to the message and a potentially used bounce buffer is freed::
+
+ i2c_release_dma_safe_msg_buf(msg, dma_buf);
+
+The bounce buffer handling from the core is generic and simple. It will always
+allocate a new bounce buffer. If you want a more sophisticated handling (e.g.
+reusing pre-allocated buffers), you are free to implement your own.
+
+Please also check the in-kernel documentation for details. The i2c-sh_mobile
+driver can be used as a reference example how to use the above helpers.
+
+Final note: If you plan to use DMA with I2C (or with anything else, actually)
+make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help
+you find various issues which can be complex to debug otherwise.
diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection
new file mode 100644
index 000000000000..e0c4f775e239
--- /dev/null
+++ b/Documentation/i2c/gpio-fault-injection
@@ -0,0 +1,54 @@
+Linux I2C fault injection
+=========================
+
+The GPIO based I2C bus master driver can be configured to provide fault
+injection capabilities. It is then meant to be connected to another I2C bus
+which is driven by the I2C bus master driver under test. The GPIO fault
+injection driver can create special states on the bus which the other I2C bus
+master driver should handle gracefully.
+
+Once the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an
+'i2c-fault-injector' subdirectory in the Kernel debugfs filesystem, usually
+mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO
+driven I2C bus. Each subdirectory will contain files to trigger the fault
+injection. They will be described now along with their intended use-cases.
+
+"scl"
+-----
+
+By reading this file, you get the current state of SCL. By writing, you can
+change its state to either force it low or to release it again. So, by using
+"echo 0 > scl" you force SCL low and thus, no communication will be possible
+because the bus master under test will not be able to clock. It should detect
+the condition of SCL being unresponsive and report an error to the upper
+layers.
+
+"sda"
+-----
+
+By reading this file, you get the current state of SDA. By writing, you can
+change its state to either force it low or to release it again. So, by using
+"echo 0 > sda" you force SDA low and thus, data cannot be transmitted. The bus
+master under test should detect this condition and trigger a bus recovery (see
+I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C
+core (see 'struct bus_recovery_info'). However, the bus recovery will not
+succeed because SDA is still pinned low until you manually release it again
+with "echo 1 > sda". A test with an automatic release can be done with the
+'incomplete_transfer' file.
+
+"incomplete_transfer"
+---------------------
+
+This file is write only and you need to write the address of an existing I2C
+client device to it. Then, a transfer to this device will be started, but it
+will stop at the ACK phase after the address of the client has been
+transmitted. Because the device will ACK its presence, this results in SDA
+being pulled low by the device while SCL is high. So, similar to the "sda" file
+above, the bus master under test should detect this condition and try a bus
+recovery. This time, however, it should succeed and the device should release
+SDA after toggling SCL. Please note: there are I2C client devices which detect
+a stuck SDA on their side and release it on their own after a few milliseconds.
+Also, there are external devices deglitching and monitoring the I2C bus. They
+can also detect a stuck SDA and will init a bus recovery on their own. If you
+want to implement bus recovery in a bus master driver, make sure you checked
+your hardware setup carefully before.