diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/code_coverage.md | 4 | ||||
| -rw-r--r-- | docs/gitlab.md | 71 | ||||
| -rw-r--r-- | docs/low_battery_startup.md | 35 | ||||
| -rw-r--r-- | docs/zephyr/README.md | 2 | ||||
| -rw-r--r-- | docs/zephyr/project_config.md | 460 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_battery.md | 5 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_charger.md | 6 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_leds.md | 48 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_mkbp.md | 2 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_new_board_checklist.md | 2 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_ssfc.md | 20 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_temperature_sensor.md | 2 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_troubleshooting.md | 8 | ||||
| -rw-r--r-- | docs/zephyr/ztest.md | 64 |
14 files changed, 144 insertions, 585 deletions
diff --git a/docs/code_coverage.md b/docs/code_coverage.md index 0a5eeb3150..49b6cfb493 100644 --- a/docs/code_coverage.md +++ b/docs/code_coverage.md @@ -80,10 +80,10 @@ The coverage report top-level page is `build/zephyr/coverage_rpt/index.html`. For coverage report for a single test you can run: -`./twister -v -i --coverage -p native_posix -p unit_testing -s external/platform/ec/zephyr/test/<testDir>/<testName>` +`./twister -v -i --coverage -p native_posix -p unit_testing -s <pathToTest>/<testName>` Example of running test tasks.default from zephyr/test/tasks/testcase.yaml: -`./twister -v -i --coverage -p native_posix -p unit_testing -s external/platform/ec/zephyr/test/tasks/tasks.default` +`./twister -v -i --coverage -p native_posix -p unit_testing -s zephyr/test/tasks/tasks.default` ## Code Coverage in CQ diff --git a/docs/gitlab.md b/docs/gitlab.md index 2ebc5c60f7..9f8d07ceec 100644 --- a/docs/gitlab.md +++ b/docs/gitlab.md @@ -45,7 +45,7 @@ sudo dpkg -i gitlab-runner_amd64.deb ### Running a Job Once Docker and the Gitlab Runner are installed, invoke it as follows. This -takes place outside of the chroot environment. +takes place outside of the ``` (outside) @@ -82,72 +82,3 @@ If you used the command as shown above, all of the build artifacts and source, as checked out by the Gitlab runner, should be under `~/gitlab-runner-output`. This will persist after the container exits but also get overwritten again on the next run. - -## Gitlab runners - -The gitlab builds run on a number of [virtual and real machines](https://gitlab.com/groups/zephyr-ec/-/runners) -which are currently at Simon's house, and cloud virtual machines. - -### Create a new VM - -* Visit https://pantheon.corp.google.com/compute/instances?onCreate=true&project=chromeos-ec-gitlab - * Click on instance-1 - * Click create similar -* Wait for new instance to be created -* Click on SSH -* Install docker -``` -sudo apt-get remove docker docker-engine docker.io containerd runc -sudo apt-get update -sudo apt-get install \ - ca-certificates \ - curl \ - gnupg \ - lsb-release -sudo mkdir -p /etc/apt/keyrings -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null -sudo apt-get update -sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin -sudo docker run hello-world -``` -* Install gitlab runner -``` -sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64 -sudo chmod +x /usr/local/bin/gitlab-runner -sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash -sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner -sudo gitlab-runner start -``` -* Register new runner using command from https://gitlab.com/groups/zephyr-ec/-/runners (click on Register a group runner, click on show instructions, click on Linux) -``` -sudo gitlab-runner register --url https://gitlab.com/ --registration-token TOKENGOESHERE -Runtime platform arch=amd64 os=linux pid=56156 revision=bbcb5aba version=15.3.0 -Running in system-mode. - -Enter the GitLab instance URL (for example, https://gitlab.com/): -[https://gitlab.com/]: -Enter the registration token: -[TOKENGOESHERE]: -Enter a description for the runner: -[instance-2]: Cloud runner instance-2 -Enter tags for the runner (comma-separated): - -Enter optional maintenance note for the runner: - -Registering runner... succeeded runner=TOKENGOESHERE -Enter an executor: docker, parallels, shell, docker-ssh+machine, custom, docker-ssh, ssh, virtualbox, docker+machine, kubernetes: -docker -Enter the default Docker image (for example, ruby:2.7): -ruby:2.7 -Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded! - -Configuration (with the authentication token) was saved in "/etc/gitlab-runner/config.toml" -``` - -* Install cleanup docker cleanup daily cron -``` -( echo "0 3 * * * /usr/bin/docker system prune -f -a --volumes" ; sudo crontab -l -u root ) | sudo crontab -u root - -``` diff --git a/docs/low_battery_startup.md b/docs/low_battery_startup.md index 1f94d4956e..48f9c28f49 100644 --- a/docs/low_battery_startup.md +++ b/docs/low_battery_startup.md @@ -77,7 +77,8 @@ analog signaling alone. Via digital communication in the PD protocol, much higher power states may be negotiated. However, higher power states also usually run at a higher voltage state as well. Any time the voltage level is changing, the power sink (the ChromeOS device) must lower its power consumption during the -transient. +transient. The standby current level is governed by +`CONFIG_CHARGER_INPUT_CURRENT`. PD port partners are capable of both soft and hard resets. Hard resets will cause a dead-bus state for a brief interval before PD can renegotiate, from @@ -168,7 +169,7 @@ is robust enough to support the device during brief intervals of PD negotiation without browning out. ``` -#define CONFIG_CHARGER_DEFAULT_CURRENT_LIMIT 512 +#define CONFIG_CHARGER_INPUT_CURRENT 512 #define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON 1 ``` @@ -205,7 +206,7 @@ the kernel and get to the login screen. ``` /* Limit battery impact during PD voltage changes. */ -#define CONFIG_CHARGER_DEFAULT_CURRENT_LIMIT 512 +#define CONFIG_CHARGER_INPUT_CURRENT 512 /* Distrust the battery SOC measurement a bit. */ #define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON 3 @@ -256,7 +257,7 @@ less. Very briefly drawing current out of the battery does not cause a brownout. Example configuration: ``` -#define CONFIG_CHARGER_DEFAULT_CURRENT_LIMIT 512 +#define CONFIG_CHARGER_INPUT_CURRENT 512 #define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON 3 #define CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON 15000 #define CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW 27000 @@ -300,7 +301,7 @@ performing a no-battery boot. Nami is an exemplar. Example configuration: ``` -#define CONFIG_CHARGER_DEFAULT_CURRENT_LIMIT 512 +#define CONFIG_CHARGER_INPUT_CURRENT 512 #define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON_WITH_AC 1 #define CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON_WITH_BATT 15000 @@ -336,27 +337,17 @@ Example configuration: ## Configuration Option Details -### `CONFIG_CHARGER_DEFAULT_CURRENT_LIMIT` +### `CONFIG_CHARGER_INPUT_CURRENT` Required. -The default charger current limit used on startup and for inactive ports. It -should not be higher than 512 mA unless the device ships with a discrete power -supply. Raising this term above 512 mA is contrary to USB-PD. It may be lowered -in order to improve compatibility with marginal BC1.2 chargers. +The lowest current limit programmed into the charger. This determines both the +default level used on startup, and the value used during the voltage transients +in PD negotiation. -### `CONFIG_CHARGER_MIN_INPUT_CURRENT_LIMIT` - -Optional. - -If set, charger input current limits will never be set lower than this value. -Historically most boards used the same value -as `CONFIG_CHARGER_DEFAULT_CURRENT_LIMIT`, but doing so violates USB-PD standby -power requirements when voltages greater than 5V are used with the default 512 -mA value. Configuring this option to a nonzero value may be useful if a board -needs extra headroom (possibly at the cost of drawing excess standby power), but -boards should prefer to override `board_set_charge_limit()` instead to limit -situations with excess power draw to only occur when that extra power is needed. +It should not be higher than 512 mA unless the device ships with a discrete +power supply. Raising this term above 512 mA is contrary to USB-PD. It may be +lowered in order to improve compatibility with marginal BC1.2 chargers. ### `CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON` diff --git a/docs/zephyr/README.md b/docs/zephyr/README.md index 84239d3b05..3b8b8dc05e 100644 --- a/docs/zephyr/README.md +++ b/docs/zephyr/README.md @@ -110,7 +110,7 @@ The following provides an overview of the sub-directories found under sub-directory. * `zephyr/linker/` - Linker directive files used to construct the Zephyr EC binaries. -* `zephyr/program/` - Program-specific configurations for each program +* `zephyr/projects/` - Program-specific configurations for each program supported by Zephyr. * `zephyr/shim/` - Source code that adapts the legacy EC APIs to the equivalent Zephyr OS API. diff --git a/docs/zephyr/project_config.md b/docs/zephyr/project_config.md index f81cc083c9..f930908502 100644 --- a/docs/zephyr/project_config.md +++ b/docs/zephyr/project_config.md @@ -3,174 +3,29 @@ Project Configuration [TOC] -## Overview - -This document defines the organization of the program and project specific files -needed by Zephyr EC projects. - -The goals of the project organization include: - -* Minimize code duplication, allowing multiple projects to share common - configuration options and devicetree nodes. -* Define the set of files required by each project. -* Define the best practices for devicetrees. - - -### Glossary - -- **program**: The name of a Chromebook reference design. The **program** - includes all Chromebooks based on a single AP SoC, such as Intel MeteorLake, - Qualcomm 7c G3, or AMD Mendocino. The **program** corresponds to a single - board overlay in the ChromeOS SDK. The term *baseboard* is often used as a - synonym for **program**. - -- **project**: The name of a specific Chromebook model or variant. All - Chromebook **programs** contain at least one **project** which serves as the - reference design(s) for the **program**. The reference **project** may or may - not use the same name as the **program**. For example, the reference - **project** for the skyrim **program** is also called skyrim. The corsola - **program** included two reference **projects**, kingler and krabby. For the - legacy ECOS builds, *board* was used as a synonym for **project**. - -This document uses bold to highlight the terms **program** and **project** to -reference the definitions above. - -## Directory Structure - -The [`zephyr/program`](../../zephyr/program) contains the **program** and -**project** configuration files for all Zephyr based EC builds. - -### `zephyr/program` directory - -Each **program** has it's own subdirectory under `zephyr/program`. - -``` -zephyr/program/ -├── brya/ -├── corsola/ -├── herobrine/ -├── intelrvp/ -├── it8xxx2_evb/ -├── minimal/ -├── nissa/ -├── npcx_evb/ -├── rex/ -├── skyrim/ -└── trogdor/ -``` - -> The [`zephyr/program/minimal`](../../zephyr/program/minimal/) **program** -contains example EC projects that demonstrate how to build a Zephyr EC with the -minimum feature set enabled. These projects require only a working UART on the -target board. - -### `zephyr/program/`**`<program>`**`/` Directory Overview - -Each **program** subdirectory contains a subdirectory foreach each **project**, -including a subdirectory for the reference **project**. - -The minimum configuration for a **program** named *skyrim* with just a single -reference **project**, also named *skyrim*, is shown below. - -``` -zephyr/program/skyrim/ -├── include/ -│ └── <program headers>.h -├── skyrim/ -│ ├── include/ -│ │ └── <project headers>.h -│ ├── src/ -│ │ └── <project sources>.c -│ ├── CMakeLists.txt -│ ├── project.conf -│ └── project.overlay -├── src/ -│ └── <program sources>.c -├── BUILD.py -├── CMakeLists.txt -├── Kconfig -├── program.conf -└── <devicetrees>.dtsi -``` - -#### `zephyr/program/`**`<program>`**`/` Directory Details - -Description of the files and directories found directly in the **<program>** -level directory. Note that all paths are relative to the `zephyr/program/` -directory. - -- **`<program>`**`/`: Top level directory for the **program**. [skyrim] is the - *program* name in the example above. -- **`<program>`**`/include/`: Directory containing the header files common to - all **projects** in the **program**. Use of **program** level includes is - discouraged. Instead, consider creating a generic driver that can be shared - across all **programs**. -- **`<program>`**`/src/`: Directory containing the C source files common to all - **projects** in the **program**. -- [**`<program>`**`/BUILD.py`](#build_py): Defines which **projects** can be - made from this directory. -- [**`<program>`**`/CMakeLists.txt`](#cmakelists_txt): CMake file for the - **program**. -- [**`<program>`**`/Kconfig`](#kconfig) - Defines new Kconfig options, used by - all **projects** in the **program**. -- [**`<program>`**`/program.conf`](#program_conf) - Sets the default Kconfig - settings for all **projects**. -- **`<program>`**`/<devictrees>.dtsi` - One or more devicetree files, organized - by the hardware module or EC feature. See the [Devicetree Best - Practices](#devicetree-best-practices) section for additional information. -- **`<program>`**`/`**`<project>`**`/`: Top level directory for the - **<project**>. Create a separate directory for each **project** defined by the - **program**. - -### `zephyr/program/`**`<program>`**`/`**`<project>`**`/` Directory Details - -Each **project** provides the following files. Note that all paths are relative -to the `zephyr/program/`**`<program>`**`/` directory. - -- **`<project>`**`/include/`: The **project** may optionally provide a public - include directory, but this is discouraged. There are some exceptions where - the legacy EC code expects the project to define a public header, such as the - keyboard_customization.h file. -- **`<project>`**`/src/`: Directory containing the C source files specific to - the **project**. -- [**`<project>`**`/CMakeLists.txt`](#cmakelists_txt): CMake file for the - **project**. -- [**`<project>`**`/project.conf`](#project_conf): Kconfig settings for the - **project**. -- [**`<project>`**`/project.overlay`](#project_overlay): Main devicetree overlay - for the **project**. - -Creation of custom C source files specific to the **program** or **project** is -discouaraged. You can usually project manage project specific settings with -Kconfig and devicetree changes only. - -Note that **program** and **project** custom C files are still subject to the -same unit test requirements. So all custom C files also require that you write -tests. - -## Setting up a new **program** - -To set up a new EC **program**, create a new directory under -[`zephyr/program`] with the organization shown below. -Note that for this example, the new **program** is called "my_program", and the -reference **project** is called "my_reference_project". - -> Tip - Copy one the **projects** defined by the [*minimal*] **program** to -> start with the bare miminimum of features required to boot the Zephyr EC -> appliation. Then follow the steps in the detailed in [Creating a New Zephyr EC -> Project]. - -``` -zephyr/program/my_program/ -├── my_reference_project/ -│ ├── CMakeLists.txt -│ ├── project.conf -│ └── project.overlay -├── BUILD.py -├── CMakeLists.txt -├── Kconfig -└── program.conf -``` +## 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: @@ -195,24 +50,18 @@ When `BUILD.py` is sourced, the following two globals are defined: 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 EC chip used. **Note:** the concept - of a Zephyr board does not align with the ChromeOS concept of a board. The - Zephyr build system requires a set of devicetree and Kconfig files under under - `boards/${ARCH}/${ZEPHYR_BOARD_NAME}`. For the Zephyr EC application, the EC - chip is mapped onto the Zephyr board organization. Supported `zephyr_boards` - include: - - `mec1727`: Microchip MEC1727, 416 KiB RAM, 512 KiB flash - - `npcx7`: Nuvoton NPCX7m7FC, 384 KiB, 512 KiB flash - - `npcx9m3f`: Nuvoton NPCX9m3F, 320 KiB RAM, 512 KiB flash - - `npcx9m7f`: Nuvoton NPCX9m7F, 384 KiB RAM, 1 MiB flash - - `it81202bx`: ITE IT81202, 60 KiB RAM, 1 MiB flash - - `it81302bx`: ITE IT81302, 60 KiB RAM, 1 MiB flash +- `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`: only supported in the chroot - - `host`: used for unit and integration tests - - `llvm`: only supported in the chroot - - `zephyr`: only supported outside the chroot + 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. @@ -228,22 +77,9 @@ When `BUILD.py` is sourced, the following two globals are defined: be used when running the test. Instances of `{test_temp_dir}` inside of an argument will be replaced with a path to a temporary directory guaranteed to be unique for the current execution. -- `dts_overlays` (optional): A list of files which should be concatenated - together and applied as a Zephyr device-tree overlay. The recommended setting - is to select the **project** specific devicetree overlay file. - - ``` python - dts_overlays=[here / project_name / "project.overlay"] - ``` - -- `kconfig_files` (optional): A list of files that contain the Kconfig settings - for the **project**. The recommended setting is select the **program** - configuration file followed by the **project** configuration file. - - ``` python - kconfig_files=[here / "program.conf", here / <project> / "project.conf",] - ``` - +- `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`. @@ -277,33 +113,18 @@ This file, should at minimum contain the following: cmake_minimum_required(VERSION 3.20.1) find_package(Zephyr REQUIRED HINTS "${ZEPHYR_BASE}") -project(**project**) -``` - -If your **program** provides any C files, add them to your program CMake file -using `zephyr_library_sources()`. - -``` cmake -zephyr_library_sources("src/my_program_source.c") -``` - -For your **project** C files, create **`<project>/`**`CMakeLists.txt` and use -`add_subdirectory()` to include the **project** CMake file. - -``` cmake -add_subdirectory("my_reference_project") +project(ec) ``` -Add the requires `zephyr_library_souces()` calls to the -**`<project>/`**`CMakeLists.txt` file. +You may additionally want to specify any C files your project needs +using `zephyr_library_sources`. If you need to add extra include +directories, use `cros_ec_library_include_directories`. -If your **program** or **project** provides a public header, make the include -directory visible to rest of the code using -`cros_ec_library_include_directories()`. +### prj.conf and prj_${project_name}.conf -``` cmake -cros_ec_library_include_directories("include") -``` +`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 @@ -315,33 +136,6 @@ 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. -### program.conf - -`program.conf` has default Kconfig settings for all **projects** defined for the -**program**. The format is `KEY=VALUE`, as typical for Kconfig. - -### project.conf - -`project.conf` has the Kconfig settings for a single **project**. The format is -`KEY=VALUE`, as typical for Kconfig. - -Kconfig settings in `project.conf` take precedence over the Kconfig settings -from `program.conf`. - -### project.overlay - -`project.overlay` is the main devicetree overlay for the **project**. The -`project.overlay` contains the following components: -- One or more `#include` statements to add devicetrees defined by the - **program** into project. -- `/delete-node/` statements to remove specific devicetree nodes defined by the - **program** devicetrees. -- New devicetree nodes for **project** specific settings that are not provided - by any **program** devicetrees. - -> Tip: After building your **project**, you can view the final devicetree in the -file `build/zephyr/`**`<project>`**`/build-ro/zephyr/zephyr.dts`. - ## Setting up a new variant of an EC program **Unlike our legacy EC, there are no files or directories to copy and @@ -400,167 +194,3 @@ With this simple variant syntax, lists (like Kconfig files and DTS overlays) are concatenated. This means it's not possible to remove files during variant registration for this syntax, so it's only recommended for the simple case. - -## Devicetree Best Practices - -Below are the best practices for devicetree organization: - -* Split the devicetree across multiple files, organized by the functional block. - This organization applies to the shared **program** devicetrees only. - * FW_CONFIG - * GPIOs - * I2C - * Interrupts - * Keyboard - * LEDs - * Sensors - * Thermal (fans and temperature sensors) - * USB-C -* When creating **program**, usually with a single reference project, add the - shared devicetree files in the program directory, separated by the functional - area noted above. -* Each project creates a `project.overlay` file, and uses `#include` statements - to add shared devicetree files from the program directory. An example - project.overlay for the skyrim project is shown below. - - ``` c - /* Copyright 2021 The ChromiumOS Authors - * Use of this source code is governed by a BSD-style license that can be - * found in the LICENSE file. - */ - - /* Skyrim program common DTS includes */ - #include "../adc.dtsi" - #include "../fan.dtsi" - #include "../gpio.dtsi" - #include "../i2c.dtsi" - #include "../interrupts.dtsi" - #include "../keyboard.dtsi" - #include "../motionsense.dtsi" - #include "../usbc.dtsi" - - /* Skyrim project node overrides */ - /* ... */ - ``` - -### Managing **project** specific settings - -When the **project** needs to make changes to the shared devicetree files, there -are two strategies: - -* For small changes, add the `/delete-node/` attribute to the `project.overlay` - file to remove the specific devices and devicetree nodes from the **project** - final devicetree. -* For larger changes, remove the corresponding `#include` statements from the - `project.overlay` file. Then,dDirectly add any required nodes to the - `project.overlay` file. - -In both cases, the shared devicetree file in the **program** directory is not -changed. - -### Small Devicetree Changes - -Examples of small devicetree changes include: -* Change the I2C peripheral address of a device. -* Changing USB-C related chips. -* Changing motionsense properties, such as the odr and ec-rate properties. -* Overriding a specific property of a node - for instance modifying the - `pinctrl-0` property to adjust the EC pins connected to a device driver. - -The example below demonstrates how to define a device in a **program** -devicetree file and then override the setting in the `project.overlay` file. - -* The herobrine program defines the TCPC at I2C address `0xb` in the file -`zephyr/program/herobrine/i2c.dtsi`. This I2C address is valid for the -herobrine, evoker, and villager projects while the hoglin project needs to -change the I2C address to `0x1b`. - - ``` c - /* zephyr/program/herobrine/i2c.dtsi */ - - &i2c1_0 { - status = "okay"; - /* ... */ - tcpc_port0: ps8xxx@b { - compatible = "parade,ps8xxx"; - reg = <0xb>; - }; - }; - ```` -* The hoglin `project.overlay` file deletes the TCPC node at address `0xb` and -creates a new node at address `0x1b`. The node name “tcpc_port0” is kept the -same, so any references to this node name do not change, such as the USB-C port -configuration. - - ``` c - /* zephyr/program/herobrine/hoglin/project.overlay */ - - #include “../i2c.dtsi” - - &i2c1_0 { - /delete-node/ ps8xxx@b; - tcpc_port0: ps8xxx@1b { - compatible = "parade,ps8xxx"; - reg = <0x1b>; - }; - }; - ``` - -While it is also possible to change a device’s I2C address by directly -overriding the `reg` property, this should not be done. Changing only the `reg` -property causes a mismatch between the node name, `ps8xxx@b`, and the actual -device address, `0x1b`. - -Your `project.overlay` file can also directly override properties defined by the -**program** devicetree files. - -* The skyrim **program** sets the I2C clock frequency for first I2C bus to fast - (400 KHz). - ``` c - /* zephyr/program/skyrim/i2c.dtsi */ - &i2c0_0 { - status = "okay"; - label = "I2C_TCPC0"; - clock-frequency = <I2C_BITRATE_FAST>; - pinctrl-0 = <&i2c0_0_sda_scl_gpb4_b5>; - pinctrl-names = "default"; - }; - ``` -* Override the I2C clock frequency to fast-plus (1 MHz) in the winterhold - `project.overlay`. - ``` c - /* zephyr/program/skyrim/winterhold/project.overlay */ - #include "../i2c.dtsi" - &i2c0_0 { - clock-frequency = <I2C_BITRATE_FAST_PLUS>; - }; - ``` -### Large Devicetree Changes - -For large devicetree changes, the preference is to copy the relevant devicetree -fragment into the `project.overlay` file and edit the fragment directly. - -Examples of large devicetree changes (or changes that don’t benefit from using -the /delete-node/ attribute) include: -* GPIOs - specifically the “named-gpios” node. This integrates better with the - arbitrage and the pinmap utility, which auto-generates the EC GPIO settings - based on schematic data. -* Changes to the motionsense sensor types. Currently x86 architectures impose a - fixed ordering for the accelerometers and gryoscopes when accessed through the - LPC memory map (see the [`EC_MEMMAP_ACC_DATA`]). Deleting nodes changes the - order of the children under the motionsense-sense node and causes the test - [`hardware.SensorAccel`] to fail. Copy the motionsense nodes into the - project.overlay file and modify as required. -* LED policies - generally each OEM/ODM defines unique LED policies for their - designs to establish differentiation for their brand. There is little value to - creating common LED policies for all **projects** in the **program**. -* Batteries - batteries also are generally specific to the OEM/ODM. Define the - **project** batteries directly in the `project.overlay` file. - - -[skyrim]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/HEAD:src/platform/ec/zephyr/program/skyrim -[`zephyr/program`]: ../../zephyr/program/ -[*minimal*]: ../../zephyr/program/minimal/ -[Creating a New Zephyr EC Project]: ./zephyr_new_board_checklist.md -[`EC_MEMMAP_ACC_DATA`]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/HEAD:src/platform/ec/include/ec_commands.h;l=181 -[`hardware.SensorAccel`]: https://crsrc.org/o/src/platform/tast-tests/src/chromiumos/tast/local/bundles/cros/hardware/sensor_accel.go;drc=8fbf2c53960bc8917a6a01fda5405cad7c17201e;l=30 diff --git a/docs/zephyr/zephyr_battery.md b/docs/zephyr/zephyr_battery.md index 02ed5d424b..3dde8cb9cf 100644 --- a/docs/zephyr/zephyr_battery.md +++ b/docs/zephyr/zephyr_battery.md @@ -17,8 +17,7 @@ Refer to [Kconfig.battery] for all sub-options controlling battery behavior. #### Enable battery feature configs -Add battery configs to either the [`program.conf`] or [`project.conf`] file for -your project. +Add battery configs to `ec/zephyr/projects/{project}/{board}/prj.conf`. Example: @@ -272,5 +271,3 @@ Usage: [ectool]: ../ap-ec-comm.md [task]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/shim/include/shimmed_task_id.h [*node label*]: https://docs.zephyrproject.org/latest/build/dts/intro.html#dt-node-labels -[`program.conf`]: ./project_config.md#program_conf -[`project.conf`]: ./project_config.md#project_conf diff --git a/docs/zephyr/zephyr_charger.md b/docs/zephyr/zephyr_charger.md index 0dc62f2b5d..8bb4f8d3f5 100644 --- a/docs/zephyr/zephyr_charger.md +++ b/docs/zephyr/zephyr_charger.md @@ -20,9 +20,7 @@ charging configuration found in [Kconfig.usb_charger]. ### Example of enabled configs -Enable and disable charger configs in either the [`program.conf`] or -[`project.conf`] file for your project. - +In `ec/zephyr/projects/{project}/{board}/prj.conf`, one may add: ``` # Charger @@ -291,5 +289,3 @@ The [chargestate] command may also be invoked. [ectool]: ../docs/ap-ec-comm.md [mapping legacy I2C port numbers to Zephyr devicetree nodes]: ./zephyr_i2c.md#mapping-legacy-i2c-port-numbers-to-zephyr-devicetree-nodes [pwr_avg]: ./zephyr_battery.md#pwr_avg -[`program.conf`]: ./project_config.md#program_conf -[`project.conf`]: ./project_config.md#project_conf diff --git a/docs/zephyr/zephyr_leds.md b/docs/zephyr/zephyr_leds.md index 3f57aea013..b29b4ab610 100644 --- a/docs/zephyr/zephyr_leds.md +++ b/docs/zephyr/zephyr_leds.md @@ -53,23 +53,23 @@ gpio-led-pins { compatible = "cros-ec,gpio-led-pins"; /* Amber - turn on yellow LED */ color_amber: color-amber { - led-pins = <&gpio_ec_chg_led_y_c1 &gpio_ec_chg_led_b_c1>; - led-values = <1 0>; + led-pins = <&gpio_ec_chg_led_y_c1 1>, + <&gpio_ec_chg_led_b_c1 0>; }; /* Blue - turn on blue LED */ color_blue: color-blue { - led-pins = <&gpio_ec_chg_led_y_c1 &gpio_ec_chg_led_b_c1>; - led-values = <0 1>; + led-pins = <&gpio_ec_chg_led_y_c1 0>, + <&gpio_ec_chg_led_b_c1 1>; }; /* White - turn on both LEDs */ color_white: color-white { - led-pins = <&gpio_ec_chg_led_y_c1 &gpio_ec_chg_led_b_c1>; - led-values = <1 1>; + led-pins = <&gpio_ec_chg_led_y_c1 1>, + <&gpio_ec_chg_led_b_c1 1>; }; /* Off - turn off both LEDs */ color_off: color-off { - led-pins = <&gpio_ec_chg_led_y_c1 &gpio_ec_chg_led_b_c1>; - led-values = <0 0>; + led-pins = <&gpio_ec_chg_led_y_c1 0>, + <&gpio_ec_chg_led_b_c1 0>; }; }; ``` @@ -77,7 +77,7 @@ GPIO LED Pins dts file example: [led_pins_herobrine.dts] #### PWM based LEDs Configure PWM based LEDs with two separate nodes. -The `pwm-leds` node, described in [pwm-leds.yaml], configures the PWM channel and frequency. +The `cros-ec,pwm-pin-config` node, described in [cros-ec,pwm_led_pin_config.yaml], configures the PWM channel and frequency. The `cros-ec,pwm-led-pins` node, described in [cros-ec,pwm_led_pins.yaml], configures the LED colors. PWM LEDs can vary duty-cycle percentage, providing finer color control over GPIO LEDs. @@ -86,14 +86,16 @@ Example: For this example, the board contains dual-channel LED, one channel controls white color intensity, and one channel controls the amber color intensity. To set the LED color to amber, the yellow channel duty-cycle is set to 100 percentage and white channel duty-cycle is set to 0. ``` -pwmleds { - compatible = "pwm-leds"; +pwm_pins { + compatible = "cros-ec,pwm-pin-config"; pwm_y: pwm_y { + #led-pin-cells = <1>; pwms = <&pwm2 0 PWM_HZ(100) PWM_POLARITY_INVERTED>; }; pwm_w: pwm_w { + #led-pin-cells = <1>; pwms = <&pwm3 0 PWM_HZ(100) PWM_POLARITY_INVERTED>; }; }; @@ -103,18 +105,18 @@ pwm-led-pins { pwm-frequency = <100>; /* Amber - turn on yellow LED */ color_amber: color-amber { - led-pwms = <&pwm_y &pwm_w>; - pwm-values = <100 0>; + led-pins = <&pwm_y 100>, + <&pwm_w 0>; }; /* White - turn on white LED */ color_white: color-white { - led-pwms = <&pwm_y &pwm_w>; - pwm-values = <0 100>; + led-pins = <&pwm_y 0>, + <&pwm_w 100>; }; /* Off - turn off both LEDs */ color_off: color-off { - led-pwms = <&pwm_y &pwm_w>; - pwm-values = <0 0>; + led-pins = <&pwm_y 0>, + <&pwm_w 0>; }; }; ``` @@ -196,7 +198,7 @@ TODO: Enable support for ledtest - Look for the gpio/pwm pins in the schematic with which the LEDs are attached to. - In the above snippet, LEDs are configured to use PWM pins and attached to PWM2 and PWM3. -- Add PWM config nodes as shown in [pwm-leds.yaml] and [led_pins_skyrim.dts]. +- Add PWM config nodes as shown in [cros-ec,pwm_led_pin_config.yaml] and [led_pins_skyrim.dts]. - Add pin nodes based on the color of the LEDs attached as shown in [cros-ec,pwm_led_pins.yaml] and [led_pins_skyrim.dts]. Name the nodes according to the LED color for readability. e.g. `color-amber` - Based on the device LED policy, create led_policy nodes as shown in [cros-ec,led_policy.yaml] and [led_policy_skyrim.dts]. @@ -212,10 +214,10 @@ TODO: Enable support for ledtest [cros-ec,led_policy.yaml]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/leds/cros-ec,led-colors.yaml [cros-ec,gpio_led_pins.yaml]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/leds/cros-ec,gpio-led-pins.yaml [cros-ec,pwm_led_pins.yaml]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/leds/cros-ec,pwm-led-pins.yaml -[pwm-leds.yaml]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/third_party/zephyr/main/dts/bindings/led/pwm-leds.yaml -[led_policy_skyrim.dts]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/program/skyrim/led_policy_skyrim.dts -[led_pins_skyrim.dts]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/program/skyrim/led_pins_skyrim.dts -[led_policy_herobrine.dts]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/program/herobrine/led_policy_herobrine.dts -[led_pins_herobrine.dts]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/program/herobrine/led_pins_herobrine.dts +[cros-ec,pwm_led_pin_config.yaml]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/leds/cros-ec,pwm-led-pin-config.yaml +[led_policy_skyrim.dts]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/projects/skyrim/led_policy_skyrim.dts +[led_pins_skyrim.dts]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/projects/skyrim/led_pins_skyrim.dts +[led_policy_herobrine.dts]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/projects/herobrine/led_policy_herobrine.dts +[led_pins_herobrine.dts]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/projects/herobrine/led_pins_herobrine.dts [Example CL enabling single port pwm based LEDs]: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3651490 [Example CL enabling dual port gpio based LEDs]: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3635067 diff --git a/docs/zephyr/zephyr_mkbp.md b/docs/zephyr/zephyr_mkbp.md index 186ea9ce44..bedc550f7d 100644 --- a/docs/zephyr/zephyr_mkbp.md +++ b/docs/zephyr/zephyr_mkbp.md @@ -76,7 +76,7 @@ Possible enums to use in these nodes are specified in file: [MKBP event mask enu ## Examples -[Lazor wake-up masks](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/program/trogdor/lazor/gpio.dts?q=ec-mkbp-host-event-wakeup-mask) +[Lazor wake-up masks](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/projects/trogdor/lazor/gpio.dts?q=ec-mkbp-host-event-wakeup-mask) For detailed descriptions of the MKBP and host event types, please see [ec_commands.h](/include/ec_commands.h) header file. diff --git a/docs/zephyr/zephyr_new_board_checklist.md b/docs/zephyr/zephyr_new_board_checklist.md index 4b3917581b..9baaaf4c42 100644 --- a/docs/zephyr/zephyr_new_board_checklist.md +++ b/docs/zephyr/zephyr_new_board_checklist.md @@ -37,7 +37,7 @@ Each feature includes the following sub-tasks: - **Example** - This section walks through a complete example for configuring an EC feature based on existing board implementation. -## Adding a new project to zmake +## Adding a new board to zmake Refer the [project configuration](project_config.md) documentation to add a new board project to zmake. diff --git a/docs/zephyr/zephyr_ssfc.md b/docs/zephyr/zephyr_ssfc.md index 6a3fe079d3..d40fdbc9c4 100644 --- a/docs/zephyr/zephyr_ssfc.md +++ b/docs/zephyr/zephyr_ssfc.md @@ -25,11 +25,11 @@ Device tree is used to define and specify the field sizes and values. ## Devicetree Nodes -The [`SSFC`] device tree nodes are defined via the [`cros-ec,cbi-ssfc`] and -[`cros-ec,cbi-ssfc-value`] YAML bindings. +The [`SSFC`] device tree nodes are defined via the [`named-cbi-ssfc`] and +[`named-cbi-ssfc-value`] YAML bindings. -The [`cros-ec,cbi-ssfc`] bindings define the name and size of each field. -The [`cros-ec,cbi-ssfc-value`] bindings allow names/values to be defined for each +The [`named-cbi-ssfc`] bindings define the name and size of each field. +The [`named-cbi-ssfc-value`] bindings allow names/values to be defined for each value that may be stored in the field. One of the values may be designated as the default, which is used if the [`CBI`] data cannot be accessed. @@ -41,12 +41,12 @@ value is used as a default, indicating the default field. An example definition is: ``` cbi-ssfc { - compatible = "cros-ec,cbi-ssfc"; + compatible = "named-cbi-ssfc"; base_sensor { enum-name = "BASE_SENSOR"; size = <3>; base_sensor_0: bmi160 { - compatible = "cros-ec,cbi-ssfc-value"; + compatible = "named-cbi-ssfc-value"; status = "okay"; value = <1>; }; @@ -55,7 +55,7 @@ cbi-ssfc { enum-name = "LID_SENSOR"; size = <3>; lid_sensor_0: bma255 { - compatible = "cros-ec,cbi-ssfc-value"; + compatible = "named-cbi-ssfc-value"; status = "okay"; value = <1>; }; @@ -64,7 +64,7 @@ cbi-ssfc { enum-name = "LIGHTBAR"; size = <2>; lightbar_0: 10_led { - compatible = "cros-ec,cbi-ssfc-value"; + compatible = "named-cbi-ssfc-value"; status = "okay"; value = <1>; }; @@ -99,6 +99,6 @@ The [`ectool cbi`] command can be used to read and set the [`SSFC`]. [`CBI`]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md [`CBI Configuration`]: ./zephyr_cbi.md [`ectool cbi`]: ./zephyr_cbi.md#testing-and-debugging -[`cros-ec,cbi-ssfc`]: ../../zephyr/dts/bindings/cbi/cros-ec,cbi-fw-config.yaml -[`cros-ec,cbi-ssfc-value`]: ../../zephyr/dts/bindings/cbi/cros-ec,cbi-fw-config-value.yaml +[`named-cbi-ssfc`]: ../../zephyr/dts/bindings/cbi/named-cbi-fw-config.yaml +[`named-cbi-ssfc-value`]: ../../zephyr/dts/bindings/cbi/named-cbi-fw-config-value.yaml [`SSFC`]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/firmware_config.md diff --git a/docs/zephyr/zephyr_temperature_sensor.md b/docs/zephyr/zephyr_temperature_sensor.md index 7be5f5ccaf..8ee87a84f7 100644 --- a/docs/zephyr/zephyr_temperature_sensor.md +++ b/docs/zephyr/zephyr_temperature_sensor.md @@ -76,7 +76,7 @@ on Zephyr-based boards. Temperature sensors are declared as separate nodes and additional properties are defined by the `cros-ec,temp-sensors` node in the device tree. This example is -from [zephyr/program/brya/temp_sensors.dts](../../zephyr/program/brya/temp_sensors.dts): +from [zephyr/projects/brya/temp_sensors.dts](../../zephyr/projects/brya/temp_sensors.dts): ``` temp_ddr_soc: ddr_soc { diff --git a/docs/zephyr/zephyr_troubleshooting.md b/docs/zephyr/zephyr_troubleshooting.md index a7a7716e5e..646240ce18 100644 --- a/docs/zephyr/zephyr_troubleshooting.md +++ b/docs/zephyr/zephyr_troubleshooting.md @@ -12,10 +12,10 @@ The build system lists the various overlay files specified by `BUILD.py`, for example: ``` --- Found devicetree overlay: /mnt/host/source/src/platform/ec/zephyr/program/brya/adc.dts --- Found devicetree overlay: /mnt/host/source/src/platform/ec/zephyr/program/brya/battery.dts --- Found devicetree overlay: /mnt/host/source/src/platform/ec/zephyr/program/brya/cbi_eeprom.dts --- Found devicetree overlay: /mnt/host/source/src/platform/ec/zephyr/program/brya/fan.dts +-- Found devicetree overlay: /mnt/host/source/src/platform/ec/zephyr/projects/brya/adc.dts +-- Found devicetree overlay: /mnt/host/source/src/platform/ec/zephyr/projects/brya/battery.dts +-- Found devicetree overlay: /mnt/host/source/src/platform/ec/zephyr/projects/brya/cbi_eeprom.dts +-- Found devicetree overlay: /mnt/host/source/src/platform/ec/zephyr/projects/brya/fan.dts ... ``` diff --git a/docs/zephyr/ztest.md b/docs/zephyr/ztest.md index d6b598b0e3..437c79d12e 100644 --- a/docs/zephyr/ztest.md +++ b/docs/zephyr/ztest.md @@ -120,39 +120,24 @@ For most use cases these are the things to remember: ## Running twister -### Run all tests under a specific directory +Run all tests under a specific directory: ```shell platform/ec$ ./twister -T path/to/my/tests ``` -### Run a specific test +Run a specific test: ```shell -platform/ec$ ./twister -s external/platform/ec/zephyr/test/<test dir>/<my.test.case> +platform/ec$ ./twister -s path/to/my/tests/my.test.case ``` -For example: -```shell -platform/ec$ ./twister -s external/platform/ec/zephyr/test/drivers/drivers.default -``` - -Explanation of this string: `external/` is not a path component, but rather a -label that indicates we are running tests from outside of the Zephyr tree; -`platform/ec/zephyr/test/` is the location of our tests relative to the first -common parent of `ZEPHYR_BASE` and `platform/ec`; `drivers` is the directory for -our driver tests, and `drivers.default` is a specific test scenario defined in -that directory's `testcase.yaml` file. - -### Run all tests with coverage - -You can find more info on code coverage at -[Zephyr ztest code coverage](../code_coverage.md#Zephyr_ztest_code_coverage). - +Run all tests with coverage (get more info on code coverage at +[Zephyr ztest code coverage](../code_coverage.md#Zephyr_ztest_code_coverage): ```shell platform/ec$ ./twister -p native_posix -p unit_testing --coverage ``` -### Get more info on twister +Get more info on twister: ```shell platform/ec$ ./twister --help ``` @@ -166,11 +151,38 @@ Other useful flags: ## Using assumptions -The `zassume*` API is used to skip tests when certain preconditions are not -met. Please don't use it. In our tests we shouldn't ever need to skip tests -since we control all dependencies. If for some reason you actually need to skip -a test use `ztest_test_skip()` since that will indicate that you intended to -skip and didn't use assume by mistake when you meant to use assert. +The `zassume_*` API is used to minimize failures while allowing us to find out +exactly what's going wrong. When writing a test, only assert on code you're +testing. Any dependencies should use the `zassume_*` API. If the assumption +fails, your test will be marked as skipped and Twister will report an error. +Generally speaking, if an assumption fails, either the test wasn't set up +correctly, or there should be another test that's testing the dependency. + +### Example: when to use an assumption + +In a given project layout we might have several components (A, B, C, and D). In +this scenario, components B, C, and D all depend on A to function. In each test +for B, C, and D we'll include the following: + +```c +static void test_suite_before(void *f) +{ + struct my_suite_fixture *fixture = f; + + zassume_ok(f->a->init(), "Failed to initialize A, see test suite 'a_init'"); +} +``` + +The above will call A's init function and assume that it returned 0 (status OK). +If this assumption fails, then B, C, and D will all be marked as skipped along +with a log message telling us to look at the test suite 'a_init'. + +Key takeaways: +1. If it's code that you depend on (module/library/logic), use assume. It's not + what you're testing, you shouldn't raise false failures. +2. Document why/where you believe that the logic should have been tested. If we + end up skipping this test, we should know where the tests that should have + caught the error belong. ## Debugging |