diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/configuration/config_ap_to_ec_comm.md | 8 | ||||
| -rw-r--r-- | docs/ec_terms.md | 2 | ||||
| -rw-r--r-- | docs/fingerprint/fingerprint-dev-for-partners.md | 2 | ||||
| -rw-r--r-- | docs/fingerprint/fingerprint.md | 2 | ||||
| -rw-r--r-- | docs/i2c-debugging.md | 3 | ||||
| -rw-r--r-- | docs/reducing_ec_image_size.md | 2 | ||||
| -rw-r--r-- | docs/schematics/dragonclaw/README.md | 4 | ||||
| -rw-r--r-- | docs/sitemap.md | 11 | ||||
| -rw-r--r-- | docs/unit_tests.md | 2 | ||||
| -rw-r--r-- | docs/zephyr/project_config.md | 174 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_build.md (renamed from docs/zephyr_build.md) | 0 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_i2c.md | 370 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_init.md (renamed from docs/zephyr_init.md) | 0 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_new_board_checklist.md | 65 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_poc_device_bringup.md (renamed from docs/zephyr_poc_device_bringup.md) | 0 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_shim.md (renamed from docs/zephyr_shim.md) | 0 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_template.md | 56 | ||||
| -rw-r--r-- | docs/zephyr/ztest.md (renamed from docs/ztest.md) | 0 |
18 files changed, 685 insertions, 16 deletions
diff --git a/docs/configuration/config_ap_to_ec_comm.md b/docs/configuration/config_ap_to_ec_comm.md index 24b309feb7..0a517401be 100644 --- a/docs/configuration/config_ap_to_ec_comm.md +++ b/docs/configuration/config_ap_to_ec_comm.md @@ -9,10 +9,10 @@ details a system level of the operation of this feature. Configure the AP to EC communication channel, picking exactly one of the following options. -- `CONFIG_HOSTCMD_SHI` - [SPI Host Interface](../ec_terms.md#shi) (SHI) -- `CONFIG_HOSTCMD_HECI` - HECI interface -- `CONFIG_HOSTCMD_LPC` - [LPC](../ec_terms.md#lpc) bus -- `CONFIG_HOSTCMD_ESPI` - [eSPI](../ec_terms.md#espi) bus +- `CONFIG_HOST_INTERFACE_SHI` - [SPI Host Interface](../ec_terms.md#shi) (SHI) +- `CONFIG_HOST_INTERFACE_HECI` - HECI interface +- `CONFIG_HOST_INTERFACE_LPC` - [LPC](../ec_terms.md#lpc) bus +- `CONFIG_HOST_INTERFACE_ESPI` - [eSPI](../ec_terms.md#espi) bus In [config.h], search for options that start with the same name as your selected communication interface. Override defaults as needed. diff --git a/docs/ec_terms.md b/docs/ec_terms.md index 3b9f88416e..d5f3690615 100644 --- a/docs/ec_terms.md +++ b/docs/ec_terms.md @@ -239,7 +239,7 @@ [BC 1.2 Specification]: <https://www.usb.org/document-library/battery-charging-v12-spec-and-adopters-agreement> [CrOS Board Info]: <https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md> [CEC Wikipedia page]: <https://en.wikipedia.org/wiki/Consumer_Electronics_Control> -[DPTF Readme]: <https://github.com/intel/dptf/blob/master/README.txt> +[DPTF Readme]: <https://github.com/intel/dptf/blob/HEAD/README.txt> [eSPI Specification]: <https://www.intel.com/content/dam/support/us/en/documents/software/chipset-software/327432-004_espi_base_specification_rev1.0.pdf> [FAFT design doc]: <https://chromium.googlesource.com/chromiumos/third_party/autotest/+/HEAD/docs/faft-design-doc.md> [I2C Specification]: <https://www.nxp.com/docs/en/user-guide/UM10204.pdf> diff --git a/docs/fingerprint/fingerprint-dev-for-partners.md b/docs/fingerprint/fingerprint-dev-for-partners.md index 2d9332db5b..4fd6673861 100644 --- a/docs/fingerprint/fingerprint-dev-for-partners.md +++ b/docs/fingerprint/fingerprint-dev-for-partners.md @@ -650,7 +650,7 @@ Make sure that this interface is disabled: <!-- https://docs.google.com/drawings/d/1YhOUD-Qf69NUdugT6n0cX7o7CWvb5begcdmJwv7ch6I --> -[Dragonclaw Rev 0.2 1.8V Rework]: https://github.com/coreboot/chrome-ec/blob/master/docs/images/dragonclaw_rev_0.2_1.8v_load_switch_rework.pdf +[Dragonclaw Rev 0.2 1.8V Rework]: https://github.com/coreboot/chrome-ec/blob/HEAD/docs/images/dragonclaw_rev_0.2_1.8v_load_switch_rework.pdf <!-- https://docs.google.com/drawings/d/1w2qbb4AsSxY-KTK2vXZ6TKeWHveWvS3Dkgh61ocu0wc --> diff --git a/docs/fingerprint/fingerprint.md b/docs/fingerprint/fingerprint.md index 51c6192670..7b55ef7827 100644 --- a/docs/fingerprint/fingerprint.md +++ b/docs/fingerprint/fingerprint.md @@ -582,7 +582,7 @@ a given device can be found by viewing `chrome://system/#platform_identity_sku`. [CBI Info]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md [Chrome OS Config SKU]: https://chromium.googlesource.com/chromiumos/platform2/+/HEAD/chromeos-config/README.md#identity [Chrome OS Project Configuration]: https://chromium.googlesource.com/chromiumos/config/+/HEAD/README.md -[Starlark]: https://docs.bazel.build/versions/master/skylark/language.html +[Starlark]: https://docs.bazel.build/versions/main/skylark/language.html [`create_fingerprint`]: https://chromium.googlesource.com/chromiumos/config/+/e1fa0d7f56eb3dd6e9378e4326de086ada46b7d3/util/hw_topology.star#444 [Morphius `config.star`]: https://chrome-internal.googlesource.com/chromeos/project/zork/morphius/+/593b657a776ed6b320c826916adc9cd845faf709/config.star#85 [regenerate the config]: https://chromium.googlesource.com/chromiumos/config/+/HEAD/README.md#making-configuration-changes-for-your-project diff --git a/docs/i2c-debugging.md b/docs/i2c-debugging.md index 125e72b777..4b6afc9a54 100644 --- a/docs/i2c-debugging.md +++ b/docs/i2c-debugging.md @@ -4,6 +4,9 @@ The EC codebase has functionality to help you debug I²C errors without pulling out the scope. Some of the debug functionality is disabled by default to save space, but can be enabled with the `CONFIG_I2C_DEBUG` option. +For Zephyr EC builds, enable I²C by adding `CONFIG_PLATFORM_EC_I2C_DEBUG=y` to +one of your project's Kconfig files. + ## Tracing You can use the `i2ctrace` command to monitor (ranges of) addresses: diff --git a/docs/reducing_ec_image_size.md b/docs/reducing_ec_image_size.md index dd7d9bbcab..4b5c5bbf31 100644 --- a/docs/reducing_ec_image_size.md +++ b/docs/reducing_ec_image_size.md @@ -452,7 +452,7 @@ Note that there are some [FAFT tests][5] that rely on the GPIO name. If you enable this option, you may also need to change firmware testing configuration [file][6]. -[1]:./zephyr_build.md#Working-outside-the-chroot +[1]:./zephyr/zephyr_build.md#Working-outside-the-chroot [2]:https://github.com/zephyrproject-rtos/zephyr/blob/main/subsys/shell/Kconfig [3]:https://docs.zephyrproject.org/latest/guides/optimizations/tools.html [4]:https://github.com/zephyrproject-rtos/zephyr/issues/2112 diff --git a/docs/schematics/dragonclaw/README.md b/docs/schematics/dragonclaw/README.md index 66fde41df8..82a2fa2681 100644 --- a/docs/schematics/dragonclaw/README.md +++ b/docs/schematics/dragonclaw/README.md @@ -6,5 +6,5 @@ Note that you'll need to download and save the HTML file from The layout file is in the [`.brd`] file. -[`.brd`]: https://raw.githubusercontent.com/coreboot/chrome-ec/master/docs/schematics/dragonclaw/dragonclaw_v0.2.brd -[schematic]: https://raw.githubusercontent.com/coreboot/chrome-ec/master/docs/schematics/dragonclaw/dragonclaw_v0.2.html +[`.brd`]: https://raw.githubusercontent.com/coreboot/chrome-ec/HEAD/docs/schematics/dragonclaw/dragonclaw_v0.2.brd +[schematic]: https://raw.githubusercontent.com/coreboot/chrome-ec/HEAD/docs/schematics/dragonclaw/dragonclaw_v0.2.html diff --git a/docs/sitemap.md b/docs/sitemap.md index 2b9f4aaaf8..7258aacd17 100644 --- a/docs/sitemap.md +++ b/docs/sitemap.md @@ -35,7 +35,7 @@ ## Testing * [Unit Tests](./unit_tests.md) - * [Porting EC unit tests to Ztest](./ztest.md) + * [Porting EC unit tests to Ztest](./zephyr/ztest.md) * [Code Coverage](./code_coverage.md) ## Updaters @@ -59,10 +59,11 @@ ## Zephyr -* [Initialization Order](./zephyr_init.md) -* [Proof-of-Concept-Device Bringup](./zephyr_poc_device_bringup.md) -* [Shimming](./zephyr_shim.md) -* [Porting EC unit tests to Ztest](./ztest.md) +* [Building Zephyr OS](./zephyr/zephyr_build.md) +* [Initialization Order](./zephyr/zephyr_init.md) +* [Proof-of-Concept-Device Bringup](./zephyr/zephyr_poc_device_bringup.md) +* [Shimming](./zephyr/zephyr_shim.md) +* [Porting EC unit tests to Ztest](./zephyr/ztest.md) ## Miscellaneous diff --git a/docs/unit_tests.md b/docs/unit_tests.md index f26a8519c8..1d9da40f9d 100644 --- a/docs/unit_tests.md +++ b/docs/unit_tests.md @@ -196,7 +196,7 @@ Build and run the test as an EC unit test: ``` For building the test as a Zephyr Ztest unit test, follow the instructions in -[Porting EC unit tests to Ztest](./ztest.md) to build the unit test for Zephyr's +[Porting EC unit tests to Ztest](./zephyr/ztest.md) to build the unit test for Zephyr's "native_posix" host-based target. <!-- mdformat off(b/139308852) --> diff --git a/docs/zephyr/project_config.md b/docs/zephyr/project_config.md new file mode 100644 index 0000000000..285e90dbdd --- /dev/null +++ b/docs/zephyr/project_config.md @@ -0,0 +1,174 @@ +Project Configuration +===================== + +[TOC] + +## Setting up a new program ("reference board" or "baseboard") + +Unlike the legacy EC codebase, Zephyr projects all live together in +one big happy directory. The intent of this design is to encourage +code-sharing between projects, and reduce the amount of copy/paste +that is required to bring up a new project. This directory can, but +does not have to, correlate to the unified build Chrome OS board, +however firmware authors can always choose a different structure if it +makes sense for the specific scenario. As a hypothetical example, +similar Chromeboxes and Chromebooks may wish to share the Zephyr EC +project directory instead of use separate directories, even if they +are using a different unified build board. + +To set up a new EC program, create a new directory under +[`zephyr/projects`](../../zephyr/projects) with the following files: + +- `BUILD.py` - specifies which builds can be made from this directory, + and what the device-tree overlays and Kconfig files are for each + build. +- `CMakeLists.txt` - Baseboard-specific C files can be listed here. +- `prj.conf` (optional) - Default Kconfig settings for all projects. +- `Kconfig` (optional) - Set options for your reference design here, + which variants can use to install optional C sources. + +An in-depth example of each file is given below: + +### BUILD.py + +`BUILD.py` is a Python-based config file for setting up your reference +board and the associated variants. The name `BUILD.py` is important +and case-sensitive: `zmake` searches for files by this +name. + +When `BUILD.py` is sourced, the following two globals are defined: + +- `here`: A `pathlib.Path` object containing the path to the directory + `BUILD.py` is located in. +- `register_project`: A function which informs `zmake` of a new + project to be built. Your `BUILD.py` file needs to call this + function one or more times. + +`register_project` takes the following keyword arguments: + +- `project_name` (required): The name of the project (typically the + Google codename). This name must be unique amongst all projects + known to `zmake`, and `zmake` will error if you choose a conflicting + name. +- `zephyr_board` (required): The name of the Zephyr board to use for + the project. The Zephyr build system expects a Zephyr board + directory under `boards/${ARCH}/${ZEPHYR_BOARD_NAME}`. **Note:** + the concept of a Zephyr board does not align with the Chrome OS + concept of a board: for most projects this will typically be the + name of the EC chip used, not the name of the model or overlay. +- `supported_toolchains` (required): A list of the toolchain names + supported by the build. Valid values are `coreboot-sdk`, `host`, + `llvm`, and `zephyr`. Note that only `coreboot-sdk` and `llvm` are + supported in the chroot, and all projects must be able to build in + the chroot, so your project must at least list one of `coreboot-sdk` + or `llvm`. +- `output_packer` (required): An output packer type which defines + which builds get generated, and how they get assembled together into + a binary. +- `modules` (optional): A list of module names required by the + project. The default, if left unspecified, is to use all modules + known by `zmake`. Generally speaking, there is no harm to including + unnecessary modules as modules are typically guarded by Kconfig + options, so the only reason to set this is if your project needs to + build in a limited environment where not all modules are available. +- `is_test` (optional): `True` if the code should be executed as a + test after compilation, `False` otherwise. Defaults to `False`. +- `dts_overlays` (optional): A list of files which should be + concatenated together and applied as a Zephyr device-tree overlay. + Defaults to no overlays (empty list). +- `project_dir` (optional): The path to where `CMakeLists.txt` and + `Kconfig` can be found for the project, defaulting to `here`. + +Note that most projects will not want to call `register_project` +directly, but instead one of the helper functions, which sets even +more defaults for you: + +- `register_host_project`: Define a project which runs in the chroot + (not on hardware). +- `register_host_test`: Just like `register_host_project`, but + `is_test` gets set to `True`. +- `register_raw_project`: Register a project which builds a single + `.bin` file, no RO+RW packing, no FMAP. +- `register_binman_project`: Register a project which builds RO and RW + sections, packed together, and including FMAP. +- `register_npcx_project`: Just like `register_binman_project`, but + expects a file generated named `zephyr.npcx.bin` for the RO section + with Nuvoton's header. + +You can find the implementation of these functions in +[`zephyr/zmake/zmake/configlib.py`](../../zephyr/zmake/zmake/configlib.py). + +`BUILD.py` files are auto-formatted with `black`. After editing a +`BUILD.py` file, please run `black BUILD.py` on it. + +### CMakeLists.txt + +This file, should at minimum contain the following: + +``` cmake +cmake_minimum_required(VERSION 3.20.1) + +find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) +project(ec) +``` + +You may additionally want to specify any C files or include +directories your project needs using `zephyr_library_sources` or +`zephyr_library_include_directories`. + +### prj.conf and prj_${project_name}.conf + +`prj.conf` has default Kconfig settings for all projects, and +`prj_${project_name}.conf` can contain overrides for certain projects. +The format is `KEY=VALUE`, as typical for Kconfig. + +### Kconfig + +If certain projects need project-specific C files or ifdefs, the only +way to do so is to create a `Kconfig` file with the options schema you +want, and use it to toggle the inclusion of certain files. + +The file must end with a single line that reads +`source "Kconfig.zephyr"`. Note that this file is optional, so it's +recommended to only include it if you really need it. + +## Setting up a new variant of an EC program + +**Unlike our legacy EC, there are no files or directories to copy and +paste to setup a new variant in Zephyr code.** + +Simply add a `register_project`-based call to the existing `BUILD.py` +for your reference board. + +Below is an example of how programs may wish to structure this in +`BUILD.py`: + +``` python +# Copyright 2021 The Chromium OS Authors. All rights reserved. +# Use of this source code is governed by a BSD-style license that can be +# found in the LICENSE file. + +def register_variant(project_name, chip="it8xx2", extra_dts_overlays=()): + register_binman_project( + project_name=project_name, + zephyr_board=chip, + dts_overlays=[ + here / "base_power_sequence.dts", + here / "i2c.dts", + **extra_dts_overlays, + ], + ) + + +# Reference board +register_variant( + project_name="asurada", + extra_dts_overlays=[here / "reference_gpios.dts"], +) + +# Variants +register_variant( + project_name="hayato", + extra_dts_overlays=[here / "hayato_gpios.dts"], +) +``` diff --git a/docs/zephyr_build.md b/docs/zephyr/zephyr_build.md index 60a9e1d97e..60a9e1d97e 100644 --- a/docs/zephyr_build.md +++ b/docs/zephyr/zephyr_build.md diff --git a/docs/zephyr/zephyr_i2c.md b/docs/zephyr/zephyr_i2c.md new file mode 100644 index 0000000000..625efa98a5 --- /dev/null +++ b/docs/zephyr/zephyr_i2c.md @@ -0,0 +1,370 @@ +# 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 + +Kconfig Option | Default state | Documentation +:--------------------------------- | :-----------: | :------------ +`CONFIG_PLATFORM_EC_I2C` | y | [EC I2C] + +The following options are available only when `CONFIG_PLATFORM_EC_I2C=y`. + +Kconfig sub-option | Default | Documentation +:-------------------------------------------- | :-----: | :------------ +`CONFIG_I2C_SHELL` | y | [CONFIG_I2C_SHELL] +`CONFIG_PLATFORM_EC_I2C_DEBUG` | n | [I2C Debug] +`CONFIG_PLATFORM_EC_I2C_DEBUG_PASSTHRU` | n | [I2C Debug Passthru] +`CONFIG_PLATFORM_EC_CONSOLE_CMD_I2C_PORTMAP` | n | [I2C Portmap] +`CONFIG_PLATFORM_EC_CONSOLE_CMD_I2C_SPEED` | n | [I2C Speed] +`CONFIG_PLATFORM_EC_HOSTCMD_I2C_CONTROL` | n | [I2C Control] +`CONFIG_PLATFORM_EC_I2C_PASSTHRU_RESTRICTED` | n | [I2C Passthru Restricted] + +## 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"` <br> `"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 <br> `I2C_BITRATE_FAST` - 400 KHz <br> `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-name = "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-name = "I2C_PORT_BATTERY"; + } + charger { + i2c-port = <&i2c0_0>; + remote-port = <0>; + enum-name = "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](../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 = <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: + +```c + named-i2c-ports { + compatible = "named-i2c-ports"; + + i2c_sensor: sensor { + i2c-port = <&i2c0_0>; + enum-name = "I2C_PORT_SENSOR"; + }; + i2c-accel { + i2c-port = <&i2c0_0>; + enum-name = "I2C_PORT_ACCEL"; + }; + i2c_usb_c0: usb-c0 { + i2c-port = <&i2c1_0>; + enum-name = "I2C_PORT_USB_C0"; + }; + i2c_usb_c1: usb-c1 { + i2c-port = <&i2c2_0>; + enum-name = "I2C_PORT_USB_C1"; + }; + usb1-mix { + i2c-port = <&i2c3_0>; + enum-name = "I2C_PORT_USB_1_MIX"; + }; + power { + i2c-port = <&i2c5_0>; + enum-name = "I2C_PORT_POWER"; + }; + battery { + i2c-port = <&i2c5_0>; + enum-name = "I2C_PORT_BATTERY"; + }; + eeprom { + i2c-port = <&i2c7_0>; + remote-port = <7>; + enum-name = "I2C_PORT_EEPROM"; + }; + charger { + i2c-port = <&i2c7_0>; + enum-name = "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 +[EC I2C]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig;?q="config%20PLATFORM_EC_I2C"&ss=chromiumos +[CONFIG_I2C_SHELL]: https://docs.zephyrproject.org/latest/reference/kconfig/CONFIG_I2C_SHELL.html +[I2C Debug]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig;?q=PLATFORM_EC_I2C_DEBUG&sq=&ss=chromiumos +[I2C Debug Passthru]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig;?q=PLATFORM_EC_I2C_DEBUG_PASSTHRU&ss=chromiumos +[I2C Portmap]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=PLATFORM_EC_CONSOLE_CMD_I2C_PORTMAP&ss=chromiumos%2Fchromiumos%2Fcodesearch +[I2C Speed]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=PLATFORM_EC_CONSOLE_CMD_I2C_SPEED&ss=chromiumos +[I2C Control]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=PLATFORM_EC_HOSTCMD_I2C_CONTROL&ss=chromiumos +[I2C Passthru Restricted]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=PLATFORM_EC_I2C_PASSTHRU_RESTRICTED&ss=chromiumos +[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; diff --git a/docs/zephyr_init.md b/docs/zephyr/zephyr_init.md index 8822736efb..8822736efb 100644 --- a/docs/zephyr_init.md +++ b/docs/zephyr/zephyr_init.md diff --git a/docs/zephyr/zephyr_new_board_checklist.md b/docs/zephyr/zephyr_new_board_checklist.md new file mode 100644 index 0000000000..c90bd4e2f2 --- /dev/null +++ b/docs/zephyr/zephyr_new_board_checklist.md @@ -0,0 +1,65 @@ +# Creating a New Zephyr EC Project + +[TOC] + +## Overview + +This document describes the high-level steps needed to create a new Zephyr EC +project for a Chromebook design. + +## Intended Audience + +This document is for use by software engineers working in the EC codebase. This +document and the linked documents provide a guide for creating new Zephyr EC +projects and for modifying/maintaining existing Zephyr EC projects. + +## How to use this document + +The following sections detail a single feature set that needs modification for +your board design. Each feature set can be implemented with a reasonably sized +change list, and can be worked on independently. + +Each feature includes the following sub-tasks: + +- **Kconfig Options** - This section details the `Kconfig` options relevant to + the feature. `Kconfig` options are enabled in one of the [project + configuration files]. +- **Devicetree Nodes** - This section details the devicetree nodes and + properties required by the feature. +- **Board Specific Code** - When present, this section details any C code that + your project must implement. +- **Threads** - This section details the threads created by the feature and + provides an overview of each thread. +- **Testing and Debugging** - This section details strategies for testing the EC + feature set and for debugging issues. This section also documents EC console + commands related to the feature set. +- **Example** - This section walks through a complete example for configuring an + EC feature based on existing board implementation. + +## Adding a new board to zmake + +Refer the [zmake](TODO) documentation to add a new board project to zmake. + +## Configure EC Features + +The checklist below provides an overview of EC features that you must configure +for correct operation of a Chromebook. The “Needed for Power On” column +indicates the critical features needed during board bringup. Use the +documentation link for details about the code changes required to implement each +feature. + +EC Feature | Needed for Power On +:-------------------------------------------------------------------------- | :-----------------: +[Configure EC Chipset (TODO)](./zephyr_template.md) | yes +[Configure AP to EC Communication (TOD0)](./zephyr_template.md) | yes +[Configure AP Power Sequencing (TODO)](./zephyr_template.md) | yes +[Configure USB-C (TODO)](./zephyr_template.md) | yes +[Configure Charger (TODO)](./zephyr_template.md) | yes +[Configure I2C Buses (TODO)](./zephyr_template.md) | yes +[Configure Batteries (TODO)](./zephyr_template.md) | no +[Configure CrOS Board Information (CBI) (TODO)](./zephyr_template.md) | no +[Configure Keyboard (TODO)](./zephyr_template.md) | no +[Configure LEDs (TODO)](./zephyr_template.md) | no +[Configure Motion Sensors (TODO)](./zephyr_template.md) | no +[Configure BC1.2 Charger Detector (TODO)](./zephyr_template.md) | no +[Configure Battery (TODO)](./zephyr_template.md) | no diff --git a/docs/zephyr_poc_device_bringup.md b/docs/zephyr/zephyr_poc_device_bringup.md index 394aa4a05b..394aa4a05b 100644 --- a/docs/zephyr_poc_device_bringup.md +++ b/docs/zephyr/zephyr_poc_device_bringup.md diff --git a/docs/zephyr_shim.md b/docs/zephyr/zephyr_shim.md index fac0383aff..fac0383aff 100644 --- a/docs/zephyr_shim.md +++ b/docs/zephyr/zephyr_shim.md diff --git a/docs/zephyr/zephyr_template.md b/docs/zephyr/zephyr_template.md new file mode 100644 index 0000000000..f75883eec9 --- /dev/null +++ b/docs/zephyr/zephyr_template.md @@ -0,0 +1,56 @@ +# Zephyr EC Feature Configuration Template + +[TOC] + +## Overview + +*Description of the Zephyr EC feature and the capabilities provided* + +## Kconfig Options + +*List the Kconfig options that enable the feature and list any sub-configuration +options that control the behavior of the feature.* + +Kconfig Option | Default | Documentation +:------------------------------------- | :-----: | :------------ +`CONFIG_PLATFORM_EC_<option>` | y/n | [zephyr/Kconfig](../zephyr/Kconfig) + +Kconfig sub-option | Default | Documentation +:------------------------------------- | :-----: | :------------ +`CONFIG_PLATFORM_EC_<option>` | y/n | [zephyr/Kconfig](../zephyr/Kconfig) + + +*Note - Avoid documenting `CONFIG_` options in the markdown as the relevant +`Kconfig*` contains the authoritative definition. Link directly to the Kconfig +option in source like this: [I2C Passthru Restricted].* + +## Devicetree Nodes + +*Detail the devicetree nodes that configure the feature.* + +*Note - avoid documenting node properties here. Point to the relevant `.yaml` +file instead, which contains the authoritative definition.* + +## Board Specific Code + +*Document any board specific routines that a user must create to successfully +compile and run. For many features, this can section can be empty.* + +## Threads + +*Document any threads enabled by this feature.* + +## Testing and Debugging + +*Provide any tips for testing and debugging the EC feature.* + +## Example + +*Provide code snippets from a working board to walk the user through +all code that must be created to enable this feature.* + +<!-- +The following demonstrates linking to a code search result for a Kconfig option. +Reference this link in your text by matching the text in brackets exactly. +--> +[I2C Passthru Restricted]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_I2C_PASSTHRU_RESTRICTED%22&ss=chromiumos diff --git a/docs/ztest.md b/docs/zephyr/ztest.md index 021b3391bd..021b3391bd 100644 --- a/docs/ztest.md +++ b/docs/zephyr/ztest.md |