From 0a0b80a44c7d111a0404d91847db57be8b667a15 Mon Sep 17 00:00:00 2001 From: Krzysztof Kozlowski Date: Tue, 2 Aug 2022 17:39:47 +0200 Subject: dt-bindings: i2c: qcom,i2c-cci: convert to dtschema Convert the Qualcomm Camera Control Interface (CCI) I2C controller to DT schema. The original bindings were not complete, so this includes changes: 1. Add address/size-cells. 2. Describe the clocks per variant. 3. Use more descriptive example based on sdm845. Signed-off-by: Krzysztof Kozlowski Reviewed-by: Rob Herring Signed-off-by: Wolfram Sang --- .../devicetree/bindings/i2c/i2c-qcom-cci.txt | 96 -------- .../devicetree/bindings/i2c/qcom,i2c-cci.yaml | 242 +++++++++++++++++++++ 2 files changed, 242 insertions(+), 96 deletions(-) delete mode 100644 Documentation/devicetree/bindings/i2c/i2c-qcom-cci.txt create mode 100644 Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml (limited to 'Documentation') 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: - 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: - Definition: base address CCI I2C controller and length of memory - mapped region. - -- interrupts: - Usage: required - Value type: - 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: - Definition: a list of phandle, should contain an entry for each - entries in clock-names. - -- clock-names - Usage: required - Value type: - Definition: a list of clock names, must include "cci" clock. - -- power-domains - Usage: required for "qcom,msm8996-cci" - Value type: - 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: - Definition: Index of the CCI bus/master - -- clock-frequency: - Usage: optional - Value type: - 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 = ; - 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 + - Robert Foss + +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 + #include + #include + + cci@ac4a000 { + reg = <0x0ac4a000 0x4000>; + compatible = "qcom,sdm845-cci"; + #address-cells = <1>; + #size-cells = <0>; + + interrupts = ; + 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>; + }; + }; + }; + }; + }; -- cgit v1.2.3 From 3a8b54298cbee5d56a710f70863226b0ed84aa27 Mon Sep 17 00:00:00 2001 From: Kewei Xu Date: Sat, 6 Aug 2022 18:02:48 +0800 Subject: dt-bindings: i2c: update bindings for mt8188 soc Add a DT binding documentation for the mt8188 soc. Signed-off-by: Kewei Xu Reviewed-by: Matthias Brugger Acked-by: Rob Herring Reviewed-by: Qii Wang Signed-off-by: Wolfram Sang --- Documentation/devicetree/bindings/i2c/i2c-mt65xx.yaml | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') 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: -- cgit v1.2.3 From 9bbebdf77890358304c7b55a02228cf00deec4cb Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Mon, 8 Aug 2022 16:17:00 +0200 Subject: docs: i2c: i2c-protocol: update introductory paragraph This sentence dates back to the pre-git era and it does not look very professional... As there is no clear definition of "finished", and given this page is already a pretty good overview, not to mention it is not the kernel responsibility to document the protocol in detail, let's update the text accordingly. Signed-off-by: Luca Ceresoli Signed-off-by: Wolfram Sang --- Documentation/i2c/i2c-protocol.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst index b2092f8f815d..9ecf03f5de33 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 ============== -- cgit v1.2.3 From 24d129d4f2bd01a085eb18ac7abb5612796209d8 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Mon, 8 Aug 2022 16:17:01 +0200 Subject: docs: i2c: i2c-protocol,smbus-protocol: remove nonsense words "as usual" does not mean much here, especially as these are introductory sections and 10-bit addressing hasn't been introduced yet. Signed-off-by: Luca Ceresoli Signed-off-by: Wolfram Sang --- Documentation/i2c/i2c-protocol.rst | 2 +- Documentation/i2c/smbus-protocol.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst index 9ecf03f5de33..7ffada1f3335 100644 --- a/Documentation/i2c/i2c-protocol.rst +++ b/Documentation/i2c/i2c-protocol.rst @@ -13,7 +13,7 @@ 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. diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst index 00d8e17d0aca..55e209c7e520 100644 --- a/Documentation/i2c/smbus-protocol.rst +++ b/Documentation/i2c/smbus-protocol.rst @@ -41,7 +41,7 @@ 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. -- cgit v1.2.3 From 0721ceee2fa7e64c1bc83b2d7aa4b8f284bc7aa0 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Mon, 8 Aug 2022 16:17:02 +0200 Subject: docs: i2c: i2c-protocol: remove unused legend items "Comm", "Count", "DataLow", "DataHigh" are not used in this section. Signed-off-by: Luca Ceresoli Signed-off-by: Wolfram Sang --- Documentation/i2c/i2c-protocol.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst index 7ffada1f3335..df0febfe6410 100644 --- a/Documentation/i2c/i2c-protocol.rst +++ b/Documentation/i2c/i2c-protocol.rst @@ -15,11 +15,7 @@ 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 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. -- cgit v1.2.3 From 6c12ec2772fa01516fde5685644b129c6f236ce2 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Mon, 8 Aug 2022 16:17:03 +0200 Subject: docs: i2c: smbus-protocol: improve DataLow/DataHigh definition Use a more professional wording. Signed-off-by: Luca Ceresoli Reviewed-by: Bagas Sanjaya Signed-off-by: Wolfram Sang --- Documentation/i2c/smbus-protocol.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst index 55e209c7e520..4942c4cad4ad 100644 --- a/Documentation/i2c/smbus-protocol.rst +++ b/Documentation/i2c/smbus-protocol.rst @@ -45,8 +45,8 @@ 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 -- cgit v1.2.3 From 43310e279d7b40c84bd41b30f2fa53d9bc05b268 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Mon, 8 Aug 2022 16:17:04 +0200 Subject: docs: i2c: instantiating-devices: add syntax coloring to dts and C blocks These blocks can be nicely coloured via Sphinx. Signed-off-by: Luca Ceresoli Signed-off-by: Wolfram Sang --- Documentation/i2c/instantiating-devices.rst | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) (limited to 'Documentation') 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 }; -- cgit v1.2.3 From 55bdfb8b55ae4bff4864d61a250abe0af86adc69 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Mon, 8 Aug 2022 16:17:07 +0200 Subject: docs: i2c: i2c-sysfs: improve wording Improve wording in a couple sentences. Signed-off-by: Luca Ceresoli [wsa: improved a little more] Signed-off-by: Wolfram Sang --- Documentation/i2c/i2c-sysfs.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/i2c/i2c-sysfs.rst b/Documentation/i2c/i2c-sysfs.rst index 6b68b95cd427..dd75008b44c8 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 ----------------------------- @@ -117,7 +116,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. :: -- cgit v1.2.3 From fe99b819487dba848cddd3d4bf4beb8e653d7e9c Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Mon, 8 Aug 2022 16:17:08 +0200 Subject: docs: i2c: i2c-sysfs: fix hyperlinks dts files cannot be linked conveniently, thus replace them with literal formatting. The links to other rst pages are broken, fix them using the proper syntax. Fixes: 31df7195b100 ("Documentation: i2c: Add doc for I2C sysfs") Signed-off-by: Luca Ceresoli Signed-off-by: Wolfram Sang --- Documentation/i2c/i2c-sysfs.rst | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) (limited to 'Documentation') diff --git a/Documentation/i2c/i2c-sysfs.rst b/Documentation/i2c/i2c-sysfs.rst index dd75008b44c8..78c54c658fa1 100644 --- a/Documentation/i2c/i2c-sysfs.rst +++ b/Documentation/i2c/i2c-sysfs.rst @@ -99,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 @@ -289,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, @@ -382,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 -`_ +Refer to section "Method 4: Instantiate from user-space" of instantiating-devices.rst -- cgit v1.2.3