The I2C buses provide access and control to on-board peripherals, including USB-C chips, battery, charging IC, and sensors.
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.
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 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_ctrl<controller>&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 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>;
};
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.
None required.
I2C support does not enable any threads.
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. |
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
For runtime troubleshooting of an I2C device, enable the I2C tracing module to log all I2C transactions initiated by the EC code.
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 |
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"; };
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"; }; };