summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2022-08-14 00:06:08 +0300
committerLinus Torvalds <torvalds@linux-foundation.org>2022-08-14 00:06:08 +0300
commit04734361953b8cc30d5552c1abe907ccfc8bc0fa (patch)
treeff403fb324e5591517223a8ade6d45eba0367fa1 /Documentation
parenta976835fdb312590ee5c085567a4e2b06da7ac33 (diff)
parentfe99b819487dba848cddd3d4bf4beb8e653d7e9c (diff)
downloadlinux-04734361953b8cc30d5552c1abe907ccfc8bc0fa.tar.xz
Merge tag 'i2c-for-5.20-part2' of git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux
Pull more i2c updates from Wolfram Sang: - two driver fixes for issues introduced this cycle - one trivial driver improvement regarding ACPI - more DTS conversion and additions - documentation updates - subsystem-wide move from strlcpy to strscpy * tag 'i2c-for-5.20-part2' of git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux: docs: i2c: i2c-sysfs: fix hyperlinks docs: i2c: i2c-sysfs: improve wording docs: i2c: instantiating-devices: add syntax coloring to dts and C blocks docs: i2c: smbus-protocol: improve DataLow/DataHigh definition docs: i2c: i2c-protocol: remove unused legend items docs: i2c: i2c-protocol,smbus-protocol: remove nonsense words docs: i2c: i2c-protocol: update introductory paragraph i2c: move core from strlcpy to strscpy i2c: move drivers from strlcpy to strscpy i2c: kempld: Support ACPI I2C device declaration i2c: mediatek: add i2c compatible for MT8188 dt-bindings: i2c: update bindings for mt8188 soc i2c: microchip-corei2c: fix erroneous late ack send dt-bindings: i2c: qcom,i2c-cci: convert to dtschema i2c: qcom-geni: Fix GPI DMA buffer sync-back
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mt65xx.yaml1
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-qcom-cci.txt96
-rw-r--r--Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml242
-rw-r--r--Documentation/i2c/i2c-protocol.rst11
-rw-r--r--Documentation/i2c/i2c-sysfs.rst24
-rw-r--r--Documentation/i2c/instantiating-devices.rst16
-rw-r--r--Documentation/i2c/smbus-protocol.rst6
7 files changed, 270 insertions, 126 deletions
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mt65xx.yaml b/Documentation/devicetree/bindings/i2c/i2c-mt65xx.yaml
index 16a1a3118204..4e730fb7be56 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mt65xx.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-mt65xx.yaml
@@ -27,6 +27,7 @@ properties:
- const: mediatek,mt8173-i2c
- const: mediatek,mt8183-i2c
- const: mediatek,mt8186-i2c
+ - const: mediatek,mt8188-i2c
- const: mediatek,mt8192-i2c
- items:
- enum:
diff --git a/Documentation/devicetree/bindings/i2c/i2c-qcom-cci.txt b/Documentation/devicetree/bindings/i2c/i2c-qcom-cci.txt
deleted file mode 100644
index 166865e48849..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-qcom-cci.txt
+++ /dev/null
@@ -1,96 +0,0 @@
-Qualcomm Camera Control Interface (CCI) I2C controller
-
-PROPERTIES:
-
-- compatible:
- Usage: required
- Value type: <string>
- Definition: must be one of:
- "qcom,msm8916-cci"
- "qcom,msm8974-cci"
- "qcom,msm8996-cci"
- "qcom,sdm845-cci"
- "qcom,sm8250-cci"
- "qcom,sm8450-cci"
-
-- reg
- Usage: required
- Value type: <prop-encoded-array>
- Definition: base address CCI I2C controller and length of memory
- mapped region.
-
-- interrupts:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: specifies the CCI I2C interrupt. The format of the
- specifier is defined by the binding document describing
- the node's interrupt parent.
-
-- clocks:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: a list of phandle, should contain an entry for each
- entries in clock-names.
-
-- clock-names
- Usage: required
- Value type: <string>
- Definition: a list of clock names, must include "cci" clock.
-
-- power-domains
- Usage: required for "qcom,msm8996-cci"
- Value type: <prop-encoded-array>
- Definition:
-
-SUBNODES:
-
-The CCI provides I2C masters for one (msm8916) or two i2c busses (msm8974,
-msm8996, sdm845, sm8250 and sm8450), described as subdevices named "i2c-bus@0"
-and "i2c-bus@1".
-
-PROPERTIES:
-
-- reg:
- Usage: required
- Value type: <u32>
- Definition: Index of the CCI bus/master
-
-- clock-frequency:
- Usage: optional
- Value type: <u32>
- Definition: Desired I2C bus clock frequency in Hz, defaults to 100
- kHz if omitted.
-
-Example:
-
- cci@a0c000 {
- compatible = "qcom,msm8996-cci";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0xa0c000 0x1000>;
- interrupts = <GIC_SPI 295 IRQ_TYPE_EDGE_RISING>;
- clocks = <&mmcc MMSS_MMAGIC_AHB_CLK>,
- <&mmcc CAMSS_TOP_AHB_CLK>,
- <&mmcc CAMSS_CCI_AHB_CLK>,
- <&mmcc CAMSS_CCI_CLK>,
- <&mmcc CAMSS_AHB_CLK>;
- clock-names = "mmss_mmagic_ahb",
- "camss_top_ahb",
- "cci_ahb",
- "cci",
- "camss_ahb";
-
- i2c-bus@0 {
- reg = <0>;
- clock-frequency = <400000>;
- #address-cells = <1>;
- #size-cells = <0>;
- };
-
- i2c-bus@1 {
- reg = <1>;
- clock-frequency = <400000>;
- #address-cells = <1>;
- #size-cells = <0>;
- };
- };
diff --git a/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml b/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml
new file mode 100644
index 000000000000..90c9e401229e
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml
@@ -0,0 +1,242 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/qcom,i2c-cci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Camera Control Interface (CCI) I2C controller
+
+maintainers:
+ - Loic Poulain <loic.poulain@linaro.org>
+ - Robert Foss <robert.foss@linaro.org>
+
+properties:
+ compatible:
+ enum:
+ - qcom,msm8916-cci
+ - qcom,msm8974-cci
+ - qcom,msm8996-cci
+ - qcom,sdm845-cci
+ - qcom,sm8250-cci
+ - qcom,sm8450-cci
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ clocks:
+ minItems: 4
+ maxItems: 6
+
+ clock-names:
+ minItems: 4
+ maxItems: 6
+
+ interrupts:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+patternProperties:
+ "^i2c-bus@[01]$":
+ $ref: /schemas/i2c/i2c-controller.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ maxItems: 1
+
+ clock-frequency:
+ default: 100000
+
+required:
+ - compatible
+ - clock-names
+ - clocks
+ - interrupts
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,msm8996-cci
+ then:
+ required:
+ - power-domains
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,msm8916-cci
+ then:
+ properties:
+ i2c-bus@1: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,msm8916-cci
+ - qcom,msm8996-cci
+ then:
+ properties:
+ clocks:
+ maxItems: 4
+ clock-names:
+ items:
+ - const: camss_top_ahb
+ - const: cci_ahb
+ - const: cci
+ - const: camss_ahb
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sdm845-cci
+ then:
+ properties:
+ clocks:
+ minItems: 6
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: soc_ahb
+ - const: slow_ahb_src
+ - const: cpas_ahb
+ - const: cci
+ - const: cci_src
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8250-cci
+ then:
+ properties:
+ clocks:
+ minItems: 5
+ maxItems: 5
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: slow_ahb_src
+ - const: cpas_ahb
+ - const: cci
+ - const: cci_src
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,camcc-sdm845.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ cci@ac4a000 {
+ reg = <0x0ac4a000 0x4000>;
+ compatible = "qcom,sdm845-cci";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ interrupts = <GIC_SPI 460 IRQ_TYPE_EDGE_RISING>;
+ power-domains = <&clock_camcc TITAN_TOP_GDSC>;
+
+ clocks = <&clock_camcc CAM_CC_CAMNOC_AXI_CLK>,
+ <&clock_camcc CAM_CC_SOC_AHB_CLK>,
+ <&clock_camcc CAM_CC_SLOW_AHB_CLK_SRC>,
+ <&clock_camcc CAM_CC_CPAS_AHB_CLK>,
+ <&clock_camcc CAM_CC_CCI_CLK>,
+ <&clock_camcc CAM_CC_CCI_CLK_SRC>;
+ clock-names = "camnoc_axi",
+ "soc_ahb",
+ "slow_ahb_src",
+ "cpas_ahb",
+ "cci",
+ "cci_src";
+
+ assigned-clocks = <&clock_camcc CAM_CC_CAMNOC_AXI_CLK>,
+ <&clock_camcc CAM_CC_CCI_CLK>;
+ assigned-clock-rates = <80000000>,
+ <37500000>;
+
+ pinctrl-names = "default", "sleep";
+ pinctrl-0 = <&cci0_default &cci1_default>;
+ pinctrl-1 = <&cci0_sleep &cci1_sleep>;
+
+ i2c-bus@0 {
+ reg = <0>;
+ clock-frequency = <1000000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@10 {
+ compatible = "ovti,ov8856";
+ reg = <0x10>;
+
+ reset-gpios = <&tlmm 9 GPIO_ACTIVE_LOW>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&cam0_default>;
+
+ clocks = <&clock_camcc CAM_CC_MCLK0_CLK>;
+ clock-names = "xvclk";
+ clock-frequency = <19200000>;
+
+ dovdd-supply = <&vreg_lvs1a_1p8>;
+ avdd-supply = <&cam0_avdd_2v8>;
+ dvdd-supply = <&cam0_dvdd_1v2>;
+
+ port {
+ ov8856_ep: endpoint {
+ link-frequencies = /bits/ 64 <360000000 180000000>;
+ data-lanes = <1 2 3 4>;
+ remote-endpoint = <&csiphy0_ep>;
+ };
+ };
+ };
+ };
+
+ cci_i2c1: i2c-bus@1 {
+ reg = <1>;
+ clock-frequency = <1000000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@60 {
+ compatible = "ovti,ov7251";
+ reg = <0x60>;
+
+ enable-gpios = <&tlmm 21 GPIO_ACTIVE_HIGH>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&cam3_default>;
+
+ clocks = <&clock_camcc CAM_CC_MCLK3_CLK>;
+ clock-names = "xclk";
+ clock-frequency = <24000000>;
+
+ vdddo-supply = <&vreg_lvs1a_1p8>;
+ vdda-supply = <&cam3_avdd_2v8>;
+
+ port {
+ ov7251_ep: endpoint {
+ data-lanes = <0 1>;
+ remote-endpoint = <&csiphy3_ep>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst
index b2092f8f815d..df0febfe6410 100644
--- a/Documentation/i2c/i2c-protocol.rst
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -2,7 +2,8 @@
The I2C Protocol
================
-This document describes the I2C protocol. Or will, when it is finished :-)
+This document is an overview of the basic I2C transactions and the kernel
+APIs to perform them.
Key to symbols
==============
@@ -12,13 +13,9 @@ S Start condition
P Stop condition
Rd/Wr (1 bit) Read/Write bit. Rd equals 1, Wr equals 0.
A, NA (1 bit) Acknowledge (ACK) and Not Acknowledge (NACK) bit
-Addr (7 bits) I2C 7 bit address. Note that this can be expanded as usual to
+Addr (7 bits) I2C 7 bit address. Note that this can be expanded to
get a 10 bit I2C address.
-Comm (8 bits) Command byte, a data byte which often selects a register on
- the device.
-Data (8 bits) A plain data byte. Sometimes, I write DataLow, DataHigh
- for 16 bit data.
-Count (8 bits) A data byte containing the length of a block operation.
+Data (8 bits) A plain data byte.
[..] Data sent by I2C device, as opposed to data sent by the
host adapter.
diff --git a/Documentation/i2c/i2c-sysfs.rst b/Documentation/i2c/i2c-sysfs.rst
index 6b68b95cd427..78c54c658fa1 100644
--- a/Documentation/i2c/i2c-sysfs.rst
+++ b/Documentation/i2c/i2c-sysfs.rst
@@ -51,11 +51,10 @@ Google Pixel 3 phone for example::
``i2c-2`` is an I2C bus whose number is 2, and ``2-0049`` is an I2C device
on bus 2 address 0x49 bound with a kernel driver.
-Terminologies
-=============
+Terminology
+===========
-First, let us define a couple of terminologies to avoid confusions in the later
-sections.
+First, let us define some terms to avoid confusion in later sections.
(Physical) I2C Bus Controller
-----------------------------
@@ -100,9 +99,7 @@ Caveat
This may be a confusing part for people who only know about the physical I2C
design of a board. It is actually possible to rename the I2C bus physical number
to a different number in logical I2C bus level in Device Tree Source (DTS) under
-section ``aliases``. See
-`arch/arm/boot/dts/nuvoton-npcm730-gsj.dts
-<../../arch/arm/boot/dts/nuvoton-npcm730-gsj.dts>`_
+section ``aliases``. See ``arch/arm/boot/dts/nuvoton-npcm730-gsj.dts``
for an example of DTS file.
Best Practice: **(To kernel software developers)** It is better to keep the I2C
@@ -117,7 +114,7 @@ Walk through Logical I2C Bus
For the following content, we will use a more complex I2C topology as an
example. Here is a brief graph for the I2C topology. If you do not understand
-this graph at the first glance, do not be afraid to continue reading this doc
+this graph at first glance, do not be afraid to continue reading this doc
and review it when you finish reading.
::
@@ -290,8 +287,7 @@ MUX channel 0, and all the way to ``i2c-19`` for the MUX channel 3.
The kernel software developer is able to pin the fanout MUX channels to a static
logical I2C bus number in the DTS. This doc will not go through the details on
how to implement this in DTS, but we can see an example in:
-`arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts
-<../../arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts>`_
+``arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts``
In the above example, there is an 8-channel I2C MUX at address 0x70 on physical
I2C bus 2. The channel 2 of the MUX is defined as ``imux18`` in DTS,
@@ -383,13 +379,9 @@ Sysfs for the I2C sensor device::
For more info on the Hwmon Sysfs, refer to the doc:
-`Naming and data format standards for sysfs files
-<../hwmon/sysfs-interface.rst>`_
+../hwmon/sysfs-interface.rst
Instantiate I2C Devices in I2C Sysfs
------------------------------------
-Refer to the doc:
-
-`How to instantiate I2C devices, Method 4: Instantiate from user-space
-<instantiating-devices.rst#method-4-instantiate-from-user-space>`_
+Refer to section "Method 4: Instantiate from user-space" of instantiating-devices.rst
diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
index 890c9360ce19..3ea056a95812 100644
--- a/Documentation/i2c/instantiating-devices.rst
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -31,7 +31,9 @@ Declare the I2C devices via devicetree
On platforms using devicetree, the declaration of I2C devices is done in
subnodes of the master controller.
-Example::
+Example:
+
+.. code-block:: dts
i2c1: i2c@400a0000 {
/* ... master properties skipped ... */
@@ -71,7 +73,9 @@ code. Instantiating I2C devices via board files is done with an array of
struct i2c_board_info which is registered by calling
i2c_register_board_info().
-Example (from omap2 h4)::
+Example (from omap2 h4):
+
+.. code-block:: c
static struct i2c_board_info h4_i2c_board_info[] __initdata = {
{
@@ -111,7 +115,9 @@ 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_client_device().
-Example (from the sfe4001 network driver)::
+Example (from the sfe4001 network driver):
+
+.. code-block:: c
static struct i2c_board_info sfe4001_hwmon_info = {
I2C_BOARD_INFO("max6647", 0x4e),
@@ -136,7 +142,9 @@ 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_scanned_device() instead of i2c_new_client_device().
-Example (from the nxp OHCI driver)::
+Example (from the nxp OHCI driver):
+
+.. code-block:: c
static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index 00d8e17d0aca..4942c4cad4ad 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -41,12 +41,12 @@ Sr Repeated start condition, used to switch from write to
P Stop condition
Rd/Wr (1 bit) Read/Write bit. Rd equals 1, Wr equals 0.
A, NA (1 bit) Acknowledge (ACK) and Not Acknowledge (NACK) bit
-Addr (7 bits) I2C 7 bit address. Note that this can be expanded as usual to
+Addr (7 bits) I2C 7 bit address. Note that this can be expanded to
get a 10 bit I2C address.
Comm (8 bits) Command byte, a data byte which often selects a register on
the device.
-Data (8 bits) A plain data byte. Sometimes, I write DataLow, DataHigh
- for 16 bit data.
+Data (8 bits) A plain data byte. DataLow and DataHigh represent the low and
+ high byte of a 16 bit word.
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