# 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_"` `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 = ; }; &i2c3 { status = "okay"; label = "I2C_USB_C0_PD"; clock-frequency = ; }; ``` ### 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` - I2C port: `&i2c_` Where `` specifies the I2C controller number (0-7), and `` 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 = ; }; ``` ### ITE IT8xxx2 ECs ITE ECs use a single devicetree node, `&i2c` to enable an I2C bus. `` specifies the I2C/SMBus channel number (0-5). ``` &i2c3 { status = "okay"; label = "I2C_USB_C0_PD"; clock-frequency = ; }; ``` ### 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 ` `recover` | Recover I2C bus | `i2c recover ` `read` | Read bytes from an I2C device | `i2c read []` `read_byte` | Read a byte from an I2C device | `i2c read_byte ` `write` | Write bytes to an I2C device | `i2c write .. ` `write_byte` | Write a byte to an I2C device | `i2c write_byte ` I2C parameter summary: Parameter | Description :-------- | :---------- `` | 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. `` | The I2C device address, specified using 7-bit notation. Valid device addresses are 0 - 0x7F. `` | The register address with the I2C device to read or write. `` | For the `read` subcommand, specifies the number of bytes to read from the I2C device. Default is 16 bytes if not specified. `` | For the `write_byte` subcommand, specifies the single data byte to write to the I2C device. `..` | 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](../i2c-debugging.md) 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. ![I2C Example] 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]. ```c &i2c0_0 { status = "okay"; clock-frequency = ; label = "I2C_SENSOR"; }; &i2c_ctrl0 { status = "okay"; }; &i2c1_0 { status = "okay"; clock-frequency = ; label = "I2C_USB_C0"; }; &i2c_ctrl1 { status = "okay"; }; &i2c2_0 { status = "okay"; clock-frequency = ; label = "I2C_USB_C1"; }; &i2c_ctrl2 { status = "okay"; }; &i2c3_0 { status = "okay"; clock-frequency = ; label = "I2C_USB_1_MIX"; }; &i2c_ctrl3 { status = "okay"; }; &i2c5_0 { status = "okay"; clock-frequency = ; label = "I2C_BATTERY"; }; &i2c_ctrl5 { status = "okay"; }; &i2c7_0 { status = "okay"; clock-frequency = ; label = "I2C_EEPROM_PWR"; isl9241: isl9241@9 { compatible = "intersil,isl9241"; reg = <0x09>; label = "ISL9241_CHARGER"; switching-frequency = ; }; }; &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: ```c 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"; }; }; ``` [I2C]: ../ec_terms.md#i2c [subcommands]: https://github.com/zephyrproject-rtos/zephyr/blob/f4a0ea7b43eee4d2ee735ab6beccc68c9d40a7d0/drivers/i2c/i2c_shell.c#L245 [I2C Example]: ../images/i2c_example.png [Kconfig.i2c]: ../../zephyr/Kconfig.i2c [`CONFIG_I2C`]: https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_I2C [`CONFIG_I2C_SHELL`]: https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_I2C_SHELL [cros-ec-i2c-port-base.yaml]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/i2c/cros-ec-i2c-port-base.yaml [volteer.dts]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/boards/arm/volteer/volteer.dts; [*node labels*]: https://docs.zephyrproject.org/latest/build/dts/intro.html#dt-node-labels