zephyr_i2c.md

Zephyr I2C Bus Configuration

[TOC]

Overview

The I2C buses provide access and control to on-board peripherals, including USB-C chips, battery, charging IC, and sensors.

Kconfig Options

The Kconfig option CONFIG_I2C enables I2C support in the EC application. Refer to Kconfig.i2c for all sub-options related to I2C support.

The upstream Zephyr I2C driver also provides I2C shell commands with the CONFIG_I2C_SHELL option.

Devicetree Nodes

The EC chip disables all I2C buses by default. Enable the I2C buses used on your design by changing the chip-specific I2C bus status property to "okay".

I2C bus properties:

Property	Description	Settings
status	Enables or disables the I2C controller	"okay" "disabled"
label	Override the EC chip specific label. We recommend changing the label to match the net name of the I2C bus. The label must begin with "I2C_".	"I2C_<net_name>"
clock-frequency	Sets the initial I2C bus frequency in Hz.	I2C_BITRATE_STANDARD - 100 KHz I2C_BITRATE_FAST - 400 KHz I2C_BITRATE_FAST_PLUS - 1 MHz

Example enabling I2C0 and I2C3 at 100 KHz and 1 MHz, respectively.

&i2c0 {
        status = "okay";
        label = "I2C_BATTERY";
        clock-frequency = <I2C_BITRATE_STANDARD>;
};
&i2c3 {
        status = "okay";
        label = "I2C_USB_C0_PD";
        clock-frequency = <I2C_BITRATE_FAST_PLUS>;
};

Nuvoton NPCX ECs

Nuvoton ECs use two devicetree nodes to describe the I2C buses used, an I2C controller and an I2C port.

Nuvoton I2C node labels use the following pattern:

• I2C controller: &i2c_ctrl<controller>
• I2C port: &i2c<controller>_<port>

Where <controller> specifies the I2C controller number (0-7), and <port> specifies the port number (0-1). You can only enable one I2C port per controller, and not all I2C controllers support both ports.

The Nuvoton I2C port contains the standard Zephyr I2C bus properties. The Nuvoton I2C controller contains only the status property.

To enable a Nuvoton I2C bus, set both the I2C controller and I2C port status property to "okay".Set the clock-frequency and label properties in the I2C port as shown below:

&i2c_ctrl4 {
        status = "okay";
};
&i2c4_1 {
        status = "okay";
        label = "I2C_EEPROM";
        clock-frequency = <I2C_BITRATE_FAST>;
};

ITE IT8xxx2 ECs

ITE ECs use a single devicetree node, &i2c<channel> to enable an I2C bus. <channel> specifies the I2C/SMBus channel number (0-5).

&i2c3 {
        status = "okay";
        label = "I2C_USB_C0_PD";
        clock-frequency = <I2C_BITRATE_STANDARD>;
};

Mapping legacy I2C port numbers to Zephyr devicetree nodes

The legacy I2C API for the Chromium EC application uses an enumeration (e.g. I2C_PORT_ACCEL, I2C_PORT_EEPROM) to specify the I2C bus during transfer operations.

The named-i2c-ports node creates the mapping between the legacy I2C bus enumeration and the Zephyr I2C bus device instance.

named-i2c-ports {
        compatible = "named-i2c-ports";
        battery {
                i2c-port = <&i2c0_0>;
                remote-port = <0>;
                enum-names = "I2C_PORT_BATTERY";
        }
};

You can map multiple enumeration values to the same Zephyr I2C bus device instance.

named-i2c-ports {
        compatible = "named-i2c-ports";
        battery {
                i2c-port = <&i2c0_0>;
                remote-port = <0>;
                enum-names = "I2C_PORT_BATTERY",
                	"I2C_PORT_CHARGER";
        }
};

Refer to the cros-ec-i2c-port-base.yaml child-binding file for details about each property.

Board Specific Code

None required.

Threads

I2C support does not enable any threads.

Testing and Debugging

Shell Command: i2c

The EC application enables the the Zephyr shell command, i2c, when CONFIG_I2C_SHELL=y. The i2c command includes the following subcommands:

Subcommand	Description	Usage
scan	Scan I2C devices	i2c scan <i2c_bus_label>
recover	Recover I2C bus	i2c recover <i2c_bus_label>
read	Read bytes from an I2C device	i2c read <i2c_bus_label> <dev_addr> <reg_addr> [<num_bytes>]
read_byte	Read a byte from an I2C device	i2c read_byte <i2c_bus_label> <dev_addr> <reg_addr>
write	Write bytes to an I2C device	i2c write <i2c_bus_label> <dev_addr> <reg_addr> <out_byte0> .. <out_byteN>
write_byte	Write a byte to an I2C device	i2c write_byte <i2c_bus_label> <dev_addr> <reg_addr> <out_byte>

I2C parameter summary:

Parameter	Description
<i2c_bus_label>	The I2C bus label property. By default this is specified by the EC vendor in the respective devicetree include file unless you override the label in your devicetree.
<dev_addr>	The I2C device address, specified using 7-bit notation. Valid device addresses are 0 - 0x7F.
<reg_addr>	The register address with the I2C device to read or write.
<num_bytes>	For the read subcommand, specifies the number of bytes to read from the I2C device. Default is 16 bytes if not specified.
<out_byte>	For the write_byte subcommand, specifies the single data byte to write to the I2C device.
<out_byte0>..<out_byteN>	For the write subcommand, specifies the data bytes to write to the I2C device.

Shell Command: i2c_portmap

The shell command i2c_portmap displays the mapping of I2C bus enumeration to the physical bus and to the remote port index.

Example i2c_portmap output from a Volteer board:

uart:~$ i2c_portmap
Zephyr physical I2C ports (9):
  0 : 0
  1 : 0
  2 : 1
  3 : 2
  4 : 3
  5 : 4
  6 : 4
  7 : 5
  8 : 5
Zephyr remote I2C ports (9):
  0 : -1
  1 : -1
  2 : -1
  3 : -1
  4 : -1
  5 : -1
  6 : -1
  7 : 7
  8 : -1

I2C Tracing

For runtime troubleshooting of an I2C device, enable the I2C tracing module to log all I2C transactions initiated by the EC code.

Example

The image below shows the I2C bus assignment for the Volteer reference board.

The Volteer reference design uses the Nuvoton NPCX EC, and needs the following I2C buses enabled:

Net Name	NPCX I2C Designator	Bus speed
EC_I2C7_EEPROM_PWR	I2C7_PORT0	400 kHz
EC_I2C5_BATTERY	I2C5_PORT0	100 kHz
EC_I2C0_SENSOR	I2C0_PORT0	400 kHz
EC_I2C1_USB_C0	I2C1_PORT0	1000 kHz
EC_I2C2_USB_C1	I2C2_PORT0	1000 kHz
EC_I2C3_USB_1_MIX	I2C3_PORT0	100 kHz

Enable Nuvoton I2C buses

The Volteer project enables the Nuvoton I2C buses in volteer.dts.

&i2c0_0 {
	status = "okay";
	clock-frequency = <I2C_BITRATE_FAST>;
	label = "I2C_SENSOR";
};
&i2c_ctrl0 {
	status = "okay";
};

&i2c1_0 {
	status = "okay";
	clock-frequency = <I2C_BITRATE_FAST_PLUS>;
	label = "I2C_USB_C0";
};
&i2c_ctrl1 {
	status = "okay";
};

&i2c2_0 {
	status = "okay";
	clock-frequency = <I2C_BITRATE_FAST_PLUS>;
	label = "I2C_USB_C1";
};
&i2c_ctrl2 {
	status = "okay";
};

&i2c3_0 {
	status = "okay";
	clock-frequency = <I2C_BITRATE_STANDARD>;
	label = "I2C_USB_1_MIX";
};
&i2c_ctrl3 {
	status = "okay";
};

&i2c5_0 {
	status = "okay";
	clock-frequency = <I2C_BITRATE_STANDARD>;
	label = "I2C_BATTERY";
};
&i2c_ctrl5 {
	status = "okay";
};

&i2c7_0 {
	status = "okay";
	clock-frequency = <I2C_BITRATE_FAST>;
	label = "I2C_EEPROM_PWR";

	isl9241: isl9241@9 {
		compatible = "intersil,isl9241";
		reg = <0x09>;
		label = "ISL9241_CHARGER";
		switching-frequency = <SWITCHING_FREQ_724KHZ>;
	};
};
&i2c_ctrl7 {
	status = "okay";
};

Map I2C Enumerations

The legacy cros-ec drivers require the board to define the following enumeration values:

I2C Enumeration Name	Volteer I2C Bus Mapping
I2C_PORT_SENSOR	EC_I2C0_SENSOR
I2C_PORT_ACCEL	EC_I2C0_SENSOR
I2C_PORT_USB_C0	EC_I2C1_USB_C0
I2C_PORT_USB_C1	EC_I2C2_USB_C1
I2C_PORT_USB_1_MIX	EC_I2C3_USB_1_MIX
I2C_PORT_POWER	EC_I2C5_BATTERY
I2C_PORT_BATTERY	EC_I2C5_BATTERY
I2C_PORT_EEPROM	EC_I2C7_EEPROM_PWR
I2C_PORT_CHARGER	EC_I2C7_EEPROM_PWR

The Volteer project establishes this map using the named-i2c-ports as shown below:

	named-i2c-ports {
		compatible = "named-i2c-ports";

		i2c_sensor: sensor {
			i2c-port = <&i2c0_0>;
			enum-names = "I2C_PORT_SENSOR",
				"I2C_PORT_ACCEL";
		};
		i2c_usb_c0: usb-c0 {
			i2c-port = <&i2c1_0>;
			enum-names = "I2C_PORT_USB_C0";
		};
		i2c_usb_c1: usb-c1 {
			i2c-port = <&i2c2_0>;
			enum-names = "I2C_PORT_USB_C1";
		};
		usb1-mix {
			i2c-port = <&i2c3_0>;
			enum-names = "I2C_PORT_USB_1_MIX";
		};
		power {
			i2c-port = <&i2c5_0>;
			enum-names = "I2C_PORT_POWER",
				"I2C_PORT_BATTERY";
		};
		eeprom {
			i2c-port = <&i2c7_0>;
			enum-names = "I2C_PORT_EEPROM",
				"I2C_PORT_CHARGER";
		};
	};