Difference between revisions of "I2C device tree configuration"

[quality revision] [quality revision]
m
imported>Frq08467


Template:ArticleMainWriter Template:ReviewersList Template:ArticleApprovedVersion


1 Article purpose[edit]

This article explains how to configure the I2C internal peripheral[1] when the peripheral is assigned to Linux® OS, and in particular:

  • how to configure the STM32 I2C peripheral
  • how to configure the STM32 external I2C devices present either on the board or on a hardware extension.

The configuration is performed using the device tree mechanism[2].

It is used by the STM32 I2C Linux® driver that registers relevant information in the I2C framework.

2 DT bindings documentation[edit]

The I2C is represented by:

  • The Generic device tree bindings for I2C busses[3]
  • The STM32 I2C controller device tree bindings[4]

3 DT configuration[edit]

This hardware description is a combination of the STM32 microprocessor device tree files (.dtsi extension) and board device tree files (.dts extension). See the Device tree for an explanation of the device tree file split.

STM32CubeMX can be used to generate the board device tree. Refer to How to configure the DT using STM32CubeMX for more details.

3.1 DT configuration (STM32 level)[edit]

At device level, the I2C controller is declared as follows:

i2c2: i2c@40013000 {
	compatible = "st,stm32f7-i2c";
	reg = <0x5c002000 0x400>;
	interrupt-names = "event", "error", "wakeup";
	interrupts-extended = <&intc GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>,
			      <&intc GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>,
			      <&exti 22 1>;
	clocks = <&rcc I2C2_K>;
	resets = <&rcc I2C2_R>;
	#address-cells = <1>;
	#size-cells = <0>;
	dmas = <&dmamux1 35 0x400 0x05>,
	       <&dmamux1 36 0x400 0x05>;
	power-domains = <&pd_core>;
	st,syscfg-fmp = <&syscfg 0x4 0x2>;
	st,syscfg-fmp-clr = <&syscfg 0x44 0x2>;
	status = "disabled";
};
Warning.png This device tree part is related to STM32 microprocessors. It must be kept as is, without being modified by the end-user.

Refer to the DTS file: stm32mp157c.dtsi[5]

3.2 DT configuration (board level)[edit]

&i2c3 {
	pinctrl-names = "default", "sleep";
	pinctrl-0 = <&i2c2_pins_a>;
	pinctrl-1 = <&i2c2_pins_sleep_a>;
	i2c-scl-rising-time-ns = <185>;
	i2c-scl-falling-time-ns = <20>;
	status = "okay";
	/delete-property/dmas;
	/delete-property/dma-names;

	ov5640: camera@3c {
         [...]
	};
};

There are two levels of device tree configuration:

  • The device tree properties related to the I²C internal peripheral and to the I²C bus which belong to i2cx node
    • pinctrl-0&1 configuration depends on hardware board configuration and how the I2C devices are connected to SCL, SDA (and SMBA if device is SMBus Compliant) pins.
      More details about pin configuration are available here: Pinctrl device tree configuration
    • clock-frequency represents the I2C bus speed : normal (100KHz), Fast (400KHz) and Fast+(up to 1MHz). This value is given in Hz.
    reg represents the I2C peripheral slave address on the bus.
    Be aware that some slave address bits can have a special meaning for the framework. For instance, the 31Template:Sup bit indicates 10-bit device capability.
    Refer to
    • i2c
    .txt[3] for further detailsi2c
    • -scl-rising/falling-time-ns are both depending on the board hardware characteristics: wires length, resistor and capacitor of the hardware design.
      These values must be provided in nanoseconds and can be measured by observing the SCL rising and falling slope on an oscilloscope. See how to measure I2C timings.
      The I2C driver uses this information to compute accurate I2C timings according to the requested clock-frequency. The STM32CubeMX implements an algorithm that follows the I2C standard and takes into account the user inputs.
      Providing wrong parameters will produce inaccurate clock-frequency.
      In case the driver fails to compute timing parameters in line with the user input (SCL raising/falling and clock frequency), the clock frequency will be downgraded to a lower frequency.
      Example: if user specifies 400 kHz as clock frequency but the algorithm fails to generate timings for the specified SCL rising and falling time, the clock frequency will be dropped to 100 kHz.
    • dmas By default, DMAs are enabled for all I2C instances. This is up to the user to remove them if not needed. /delete-property/ is used to remove DMA usage for I2C. Both /delete-property/dma-names and /delete-property/dma have to be inserted to get rid of DMAs.
  • The device tree properties related to I²C devices connected to the specified I²C bus. Each I²C device is represented by a sub-node.
    • reg represents the I2C peripheral slave address on the bus.
      Be aware that some slave address bits can have a special meaning for the framework. For instance, the 31Template:Sup bit indicates 10-bit device capability.
      Refer to i2c.txt[3] for further details

3.3 DT configuration examples[edit]

Example #1: with

3.3.1 How to measure I2C timings[edit]

i2c-scl-rising-time-ns is measured on the SCL rising edge and i2c-scl-falling-time-ns on the SCL falling edge. On the oscilloscope, measure the time between the 20% to 80% range of amplitude for rising time and falling time in nanoseconds.

Alternate text
I2C timings

3.3.2 Example of an external EEPROM slave device

:

[edit]

i2c4: {
    status = "okay";
    i2c-scl-rising-time-ns = <185>;
    i2c-scl-falling-time-ns = <20>;
   
    eeprom@50 {
        compatible = "at,24c256";
        pagesize = <64>;
        reg = <0x50>;
    };
};

The above example registers an EEPROM device on i2c-X bus (X depends on how many adapters are probed at runtime) at address 0x50 and this instance is compatible with the driver registered with the same compatible property.
Please note that the driver is going to use MDMA for data transfer and that SCL rising/falling times have been provided as inputs.
Example #2: register

3.3.3 Example of an EEPROM slave device emulator registering on STM32 side

:

[edit]

i2c4: {
    eeprom@64 {
        status = "okay";
        compatible = "linux,slave-24c02";
        reg = <0x40000064>;
    };
};

The above example registers an EEPROM emulator on STM32 side at slave address 0x64.
STM32 acts as an I2C EEPROM that can be accessed from an external master device connected on I2C bus.

4 How to configure the DT using STM32CubeMX[edit]

The STM32CubeMX tool can be used to configure the STM32MPU device and get the corresponding platform configuration device tree files.
The STM32CubeMX may not support all the properties described in the above DT bindings documentation paragraph. If so, the tool inserts user sections in the generated device tree. These sections can then be edited to add some properties and they are preserved from one generation to another. Refer to STM32CubeMX user manual for further information.

5 References[edit]

Please refer to the following links for additional information:

<noinclude>

{{ArticleBasedOnModel | [[Peripheral or framework device tree configuration model]]}}
{{ArticleMainWriter | Pierre-YvesM}}
{{ArticleApprovedVersion | ReviewersList|Pierre-YvesM | FabriceG, GeraldB, ErwanL | No previous approved version , BichH, FabriceG}}
{{ArticleApprovedVersion | BichH | FabriceG, GeraldB, ErwanL | 12Oct'18 | AlainF - 11Oct'18 - 9163 | 12Oct'18}}05Feb'19}} [[Category:Device tree configuration]]
[[Category:I2C]]</noinclude>


== Article purpose ==
This article explains how to configure the ''I2C internal peripheral''<ref name="I2C internal peripheral"> [[I2C internal peripheral]] </ref> ''' when the peripheral is assigned to Linux<sup>&reg;</sup> OS''', and in particular:
* how to configure the STM32 I2C peripheral
* how to configure the STM32 external I2C devices present either on the board or on a hardware extension.

The configuration is performed using the '''device tree mechanism'''<ref> [[Device tree]]</ref>.

It is used by the ''STM32 I2C Linux<sup>&reg;</sup> driver'' that registers relevant information in the [[I2C overview|I2C]] framework.

== DT bindings documentation ==
The I2C is represented by:
* The ''Generic device tree bindings for I2C busses''<ref name="i2c.txt">{{CodeSource | Linux kernel | Documentation/devicetree/bindings/i2c/i2c.txt}}, Generic device tree bindings for I2C busses</ref>

* The ''STM32 I2C controller device tree bindings''<ref name="i2c-stm32.txt ">{{CodeSource |Linux kernel | Documentation/devicetree/bindings/i2c/i2c-stm32.txt}}</ref>


== DT configuration ==
This hardware description is a combination of the '''STM32 microprocessor''' device tree files (''.dtsi'' extension) and '''board''' device tree files (''.dts'' extension). See the [[Device tree]] for an explanation of the device tree file split.

'''STM32CubeMX''' can be used to generate the board device tree. Refer to [[#How_to_configure_the_DT_using_STM32CubeMX|How to configure the DT using STM32CubeMX]] for more details.

===DT configuration (STM32 level) ===

At device level, the I2C controller is declared as follows:<pre class="brush:c; tab-size:8;gutter:true;">

i2c2: i2c@40013000 {
	compatible = "st,stm32f7-i2c";
	reg = <0x5c002000 0x400>;
	interrupt-names = "event", "error", "wakeup";
	interrupts-extended = <&intc GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>,<&intc GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>,<&exti 22 1>;
	clocks = <&rcc I2C2_K>;
	resets = <&rcc I2C2_R>;
	#address-cells = <1>;
	#size-cells = <0>;
	dmas = <&dmamux1 35 0x400 0x05>,<&dmamux1 36 0x400 0x05>;
	power-domains = <&pd_core>;
	st,syscfg-fmp = <&syscfg 0x4 0x2>;st,syscfg-fmp-clr = <&syscfg 0x44 0x2>;status = "disabled";
};</pre>

{{Warning|This device tree part is related to STM32 microprocessors. It must be kept as is, without being modified by the end-user.}}

Refer to the DTS file: stm32mp157c.dtsi<ref name=DTS>{{CodeSource | Linux kernel | arch/arm/boot/dts/stm32mp157c.dtsi}}</ref>


=== DT configuration (board level) ===<pre class="brush:c; tab-size:8;gutter:true;">

&i2c3 {
	pinctrl-names = "default", "sleep";
	pinctrl-0 = <&i2c2_pins_a>;
	pinctrl-1 = <&i2c2_pins_sleep_a>;
	i2c-scl-rising-time-ns = <185>;
	i2c-scl-falling-time-ns = <20>;
	status = "okay";
	/delete-property/dmas;
	/delete-property/dma-names;

	ov5640: camera@3c {
         [...]
	};
};</pre>

* There are two levels of device tree configuration:
* The device tree properties related to the I²C internal peripheral and to the I²C bus which belong to i2cx node
** '''{{highlight|pinctrl-0&1}}''' configuration depends on hardware board configuration and how the I2C devices are connected to SCL, SDA (and SMBA if device is SMBus Compliant) pins.<br/> More details about pin configuration are available here: [[Pinctrl device tree configuration]] 
** '''{{highlight|clock-frequency}}''' represents the I2C bus speed : '''normal (100KHz)''', '''Fast (400KHz)''' and '''Fast+(up to 1MHz)'''. This value is given in Hz.
* '''{{highlight|reg}}''' represents the I2C peripheral slave address on the bus.<br/> Be aware that some slave address bits can have a special meaning for the framework. For instance, the 31{{sup|st}} bit indicates 10-bit device capability.<br/> Refer to i2c.txt<ref name="i2c.txt"/> for further details* '''{{highlight|i2c-scl-rising/falling-time-ns}}''' are both depending on the board hardware characteristics: wires length, resistor and capacitor of the hardware design.<br/> These values must be provided in nanoseconds and can be measured by observing the SCL rising and falling slope on an oscilloscope.<br/>  See [[I2C device tree configuration#How to measure I2C timings | how to measure I2C timings]].<br/>The I2C driver uses this information to compute accurate I2C timings according to the requested ''{{highlight|clock-frequency}}''. The STM32CubeMX implements an algorithm that follows the I2C standard and takes into account the user inputs.<br/> Providing wrong parameters will produce inaccurate ''{{highlight|clock-frequency}}''.<br/> In case the driver fails to compute timing parameters in line with the user input (SCL raising/falling and clock frequency), the clock frequency will be downgraded to a lower frequency.<br/> '''Example''': if user specifies 400 kHz as clock frequency but the algorithm fails to generate timings for the specified SCL rising and falling time, the clock frequency will be dropped to 100 kHz.{{ReviewsComments|22June'18 : AnthonyN :
Algo exists, but how calculate this I2C_TIMING Value ?<br/>

Perhaps, mention that I2C_Timing could be generated by STM32CubeMX ?
PYM: W837: Done}}

*** '''{{highlight|dmas}}''' By default, DMAs are enabled for all I2C instances. This is up to the user to '''remove''' them if not needed. ''{{highlight|/delete-property/}}'' is used to remove DMA usage for I2C. Both '''{{highlight|/delete-property/dma-names}}''' and '''{{highlight|/delete-property/dma}}''' have to be inserted to get rid of DMAs.

=== DT configuration examples ===
'''Example #1:''' with * The device tree properties related to I²C devices connected to the specified I²C bus. Each I²C device is represented by a sub-node.
** '''{{highlight|reg}}''' represents the I2C peripheral slave address on the bus.<br/> Be aware that some slave address bits can have a special meaning for the framework. For instance, the 31{{sup|st}} bit indicates 10-bit device capability.<br/> Refer to i2c.txt<ref name="i2c.txt"/> for further details

=== DT configuration examples ===
====How to measure I2C timings====
{{highlight|i2c-scl-rising-time-ns}} is measured on the SCL rising edge and {{highlight|i2c-scl-falling-time-ns}} on the SCL falling edge. On the oscilloscope, measure the time between the 20% to 80% range of amplitude for rising time and falling time in nanoseconds.<br/>

[[File:I2C timings.png|thumb|link=|center|766px|alt=Alternate text|I2C timings]]
====Example of an external EEPROM slave device:====
<pre class="brush:c; tab-size:8;gutter:true;">

i2c4: {
    status = "okay";
    i2c-scl-rising-time-ns = <185>;
    i2c-scl-falling-time-ns = <20>;

    eeprom@50 {
        compatible = "at,24c256";
        pagesize = <64>;
        reg = <0x50>;
    };
};</pre>

The above example registers an EEPROM device on i2c-X bus (X depends on how many adapters are probed at runtime) at address 0x50 and this instance is compatible with the driver registered with the same compatible property.<br/>

Please note that the driver is going to use MDMA for data transfer and that SCL rising/falling times have been provided as inputs.<br/>

'''====Example #2:''' register of an EEPROM slave device emulator registering on STM32 side:====
<pre class="brush:c; tab-size:8;gutter:true;">

i2c4: {
    eeprom@64 {
        status = "okay";
        compatible = "linux,slave-24c02";
        reg = <0x40000064>;
    };
};</pre>

The above example registers an EEPROM emulator on STM32 side at slave address 0x64. <br/>

STM32 acts as an I2C EEPROM that can be accessed from an external master device connected on I2C bus.

==How to configure the DT using STM32CubeMX==
The [[STM32CubeMX]] tool can be used to configure the STM32MPU device and get the corresponding [[Device_tree#STM32|platform configuration device tree]] files.<br />

The STM32CubeMX may not support all the properties described in the above [[#DT bindings documentation|DT bindings documentation]] paragraph. If so, the tool inserts '''user sections''' in the generated device tree. These sections can then be edited to add some properties and they are preserved from one generation to another. Refer to [[STM32CubeMX]] user manual for further information.

==References==
Please refer to the following links for additional information:
<references />
Line 2: Line 2:
 
{{ArticleBasedOnModel | [[Peripheral or framework device tree configuration model]]}}
 
{{ArticleBasedOnModel | [[Peripheral or framework device tree configuration model]]}}
 
{{ArticleMainWriter | Pierre-YvesM}}
 
{{ArticleMainWriter | Pierre-YvesM}}
{{ArticleApprovedVersion | Pierre-YvesM | FabriceG, GeraldB, ErwanL | No previous approved version | AlainF - 11Oct'18 - 9163 | 12Oct'18}}
+
{{ReviewersList|Pierre-YvesM, BichH, FabriceG}}
  +
{{ArticleApprovedVersion | BichH | FabriceG, GeraldB, ErwanL | 12Oct'18 | AlainF - 11Oct'18 - 9163 | 05Feb'19}}  
 
[[Category:Device tree configuration]]
 
[[Category:Device tree configuration]]
 
[[Category:I2C]]
 
[[Category:I2C]]
Line 45: Line 46:
 
power-domains = <&pd_core>;
 
power-domains = <&pd_core>;
 
st,syscfg-fmp = <&syscfg 0x4 0x2>;
 
st,syscfg-fmp = <&syscfg 0x4 0x2>;
  +
st,syscfg-fmp-clr = <&syscfg 0x44 0x2>;
 
status = "disabled";
 
status = "disabled";
 
};
 
};
Line 70: Line 72:
 
</pre>
 
</pre>
   
* '''{{highlight|pinctrl-0&1}}''' configuration depends on hardware board configuration and how the I2C devices are connected to SCL, SDA (and SMBA if device is SMBus Compliant) pins.<br/> More details about pin configuration are available here: [[Pinctrl device tree configuration]]  
+
There are two levels of device tree configuration:
* '''{{highlight|clock-frequency}}''' represents the I2C bus speed : '''normal (100KHz)''', '''Fast (400KHz)''' and '''Fast+(up to 1MHz)'''. This value is given in Hz.
+
* The device tree properties related to the I²C internal peripheral and to the I²C bus which belong to i2cx node
* '''{{highlight|reg}}''' represents the I2C peripheral slave address on the bus.<br/> Be aware that some slave address bits can have a special meaning for the framework. For instance, the 31{{sup|st}} bit indicates 10-bit device capability.<br/> Refer to i2c.txt<ref name="i2c.txt"/> for further details
+
** '''{{highlight|pinctrl-0&1}}''' configuration depends on hardware board configuration and how the I2C devices are connected to SCL, SDA (and SMBA if device is SMBus Compliant) pins.<br/> More details about pin configuration are available here: [[Pinctrl device tree configuration]]  
* '''{{highlight|i2c-scl-rising/falling-time-ns}}''' are both depending on the board hardware characteristics: wires length, resistor and capacitor of the hardware design.<br/> These values must be provided in nanoseconds and can be measured by observing the SCL rising and falling slope on an oscilloscope.<br/> The I2C driver uses this information to compute accurate I2C timings according to the requested ''{{highlight|clock-frequency}}''. The STM32CubeMX implements an algorithm that follows the I2C standard and takes into account the user inputs.<br/> Providing wrong parameters will produce inaccurate ''{{highlight|clock-frequency}}''.<br/> In case the driver fails to compute timing parameters in line with the user input (SCL raising/falling and clock frequency), the clock frequency will be downgraded to a lower frequency.<br/> '''Example''': if user specifies 400 kHz as clock frequency but the algorithm fails to generate timings for the specified SCL rising and falling time, the clock frequency will be dropped to 100 kHz.
+
** '''{{highlight|clock-frequency}}''' represents the I2C bus speed : '''normal (100KHz)''', '''Fast (400KHz)''' and '''Fast+(up to 1MHz)'''. This value is given in Hz.
{{ReviewsComments|22June'18 : AnthonyN :
+
** '''{{highlight|i2c-scl-rising/falling-time-ns}}''' are both depending on the board hardware characteristics: wires length, resistor and capacitor of the hardware design.<br/> These values must be provided in nanoseconds and can be measured by observing the SCL rising and falling slope on an oscilloscope. See [[I2C device tree configuration#How to measure I2C timings | how to measure I2C timings]].<br/>The I2C driver uses this information to compute accurate I2C timings according to the requested ''{{highlight|clock-frequency}}''. The STM32CubeMX implements an algorithm that follows the I2C standard and takes into account the user inputs.<br/> Providing wrong parameters will produce inaccurate ''{{highlight|clock-frequency}}''.<br/> In case the driver fails to compute timing parameters in line with the user input (SCL raising/falling and clock frequency), the clock frequency will be downgraded to a lower frequency.<br/> '''Example''': if user specifies 400 kHz as clock frequency but the algorithm fails to generate timings for the specified SCL rising and falling time, the clock frequency will be dropped to 100 kHz.
Algo exists, but how calculate this I2C_TIMING Value ?<br/>
+
** '''{{highlight|dmas}}''' By default, DMAs are enabled for all I2C instances. This is up to the user to '''remove''' them if not needed. ''{{highlight|/delete-property/}}'' is used to remove DMA usage for I2C. Both '''{{highlight|/delete-property/dma-names}}''' and '''{{highlight|/delete-property/dma}}''' have to be inserted to get rid of DMAs.
Perhaps, mention that I2C_Timing could be generated by STM32CubeMX ?
+
* The device tree properties related to I²C devices connected to the specified I²C bus. Each I²C device is represented by a sub-node.
PYM: W837: Done}}
+
** '''{{highlight|reg}}''' represents the I2C peripheral slave address on the bus.<br/> Be aware that some slave address bits can have a special meaning for the framework. For instance, the 31{{sup|st}} bit indicates 10-bit device capability.<br/> Refer to i2c.txt<ref name="i2c.txt"/> for further details
 
 
* '''{{highlight|dmas}}''' By default, DMAs are enabled for all I2C instances. This is up to the user to '''remove''' them if not needed. ''{{highlight|/delete-property/}}'' is used to remove DMA usage for I2C. Both '''{{highlight|/delete-property/dma-names}}''' and '''{{highlight|/delete-property/dma}}''' have to be inserted to get rid of DMAs.
 
   
 
=== DT configuration examples ===
 
=== DT configuration examples ===
'''Example #1:''' with an external EEPROM slave device:
+
====How to measure I2C timings====
  +
{{highlight|i2c-scl-rising-time-ns}} is measured on the SCL rising edge and {{highlight|i2c-scl-falling-time-ns}} on the SCL falling edge. On the oscilloscope, measure the time between the 20% to 80% range of amplitude for rising time and falling time in nanoseconds.<br/>
  +
[[File:I2C timings.png|thumb|link=|center|766px|alt=Alternate text|I2C timings]]
  +
====Example of an external EEPROM slave device====
 
<pre class="brush:c; tab-size:8;gutter:true;">
 
<pre class="brush:c; tab-size:8;gutter:true;">
 
i2c4: {
 
i2c4: {
Line 99: Line 102:
 
Please note that the driver is going to use MDMA for data transfer and that SCL rising/falling times have been provided as inputs.<br/>
 
Please note that the driver is going to use MDMA for data transfer and that SCL rising/falling times have been provided as inputs.<br/>
   
'''Example #2:''' register an EEPROM slave device emulator on STM32 side:
+
====Example of an EEPROM slave device emulator registering on STM32 side====
 
<pre class="brush:c; tab-size:8;gutter:true;">
 
<pre class="brush:c; tab-size:8;gutter:true;">
 
i2c4: {
 
i2c4: {