I2C device tree configuration





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.
    • i2c-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]

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.

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:

Inter-Integrated Circuit

Operating System

Device Tree

Generic Interrupt Controller

Serial Peripheral Interface

Device Tree Source (in software context) or Digital Temperature Sensor (in peripheral context)

Serial clock line

Serial DAta line

System Management Bus

Direct Memory Access

Electrically-erasable programmable read-only memory

Attachments

Discussions