diff options
Diffstat (limited to 'docs')
35 files changed, 1039 insertions, 158 deletions
diff --git a/docs/code_coverage.md b/docs/code_coverage.md index a15c61b358..7f0c544692 100644 --- a/docs/code_coverage.md +++ b/docs/code_coverage.md @@ -23,6 +23,29 @@ data into a code coverage report using the `lcov` and `genhtml` tools. The coverage report top-level page is `build/coverage/coverage_rpt/index.html`. +To get a report for one specific board's coverage run these commands: + +``` +BOARD=eldrid +make -j$(nproc) build/coverage/initial-${BOARD}.info test-coverage +# Merge board coverage and test coverage +lcov -o build/coverage/${BOARD}_merged.info --rc lcov_branch_coverage=1 \ + -a build/coverage/initial-${BOARD}.info -a build/coverage/lcov.info +# Filter out some unhelpful paths +lcov -o build/coverage/${BOARD}_filtered.info --rc lcov_branch_coverage=1 \ + -r build/coverage/${BOARD}_merged.info ${PWD}'/third_party/**' \ + ${PWD}'/build/**' '/usr/include/**' '/usr/lib/**' '${PWD}/test/**' \ + ${PWD}'/private/fingerprint/google-fpalg/mcutest/**' +# Restrict to only files used by the board +grep "SF:" "build/coverage/initial-${BOARD}.info" | sort -u | \ + sed -e 's|^SF:||' | xargs lcov --rc lcov_branch_coverage=1 \ + -o build/coverage/${BOARD}_final.info \ + -e build/coverage/${BOARD}_filtered.info +# Generate HTML +genhtml --branch-coverage -q -o build/coverage/${BOARD}_rpt \ + -t "${BOARD} coverage" -s build/coverage/${BOARD}_final.info +``` + ### Noise in the build output When building for code coverage, you may see multiple warnings of the form @@ -38,28 +61,90 @@ appear to be caused in part by using relative paths instead of absolute paths.) To build the Zephyr unit tests for code coverage run: -`zmake test --host-tests-only --coverage` -`genhtml -q -o build/zephyr/coverage_rpt/ build/zephyr/all_tests.info` +`./twister -v -i --coverage -p native_posix -p unit_testing` The coverage report top-level page is -`build/zephyr/coverage_rpt/index.html`. +`twister-out/coverage/index.html`. However you probably want to merge that with a single board's coverage report also, so that you can include code that is not part of any test as well. ``` zmake build --coverage herobrine -zmake test --host-tests-only --coverage +./twister -v -i --coverage -p native_posix -p unit_testing genhtml -q -s --branch-coverage -o build/zephyr/coverage_rpt/ \ - build/zephyr/all_tests.info build/zephyr/herobrine/output/zephyr.info + twister-out/coverage.info build/zephyr/herobrine/output/zephyr.info ``` The coverage report top-level page is `build/zephyr/coverage_rpt/index.html`. For coverage report for a single test you can run: -`zmake test --coverage <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 zephyr/test/tasks/tasks.default` + +## Code Coverage in CQ + +There are several ways to see the code coverage without running the tests +locally, depending on what information you want to see. Many of the links +below are only available to Googlers or TVCs with google.com accounts. + +### Code search + +To see the coverage of each directory, visit +http://cs/chromeos_public/src/platform/ec/ and turn on the "Directory Coverage" +layer. The denominator for the percentage covered is not clear, so these +numbers are really only useful if you are looking in very general terms. I.e. +zephyr is covered better than common. Don't get too fixated on the specific +percent shown. The results are also the last 7 days of builds combined, so there +may be some odd results if the code has changed greatly in the last week. + + + +The coverage of files is much more useful. If you are about to write a test +and not sure what to focus on, you can look at the uncovered lines in code +search. Visit [a file](http://cs/chromeos_public/src/platform/ec/common/mkbp_event.c) +in code search and make sure the "File Coverage" layer is enabled. Lines that +are not covered by any test are in red, tested lines are in green, and uncolored +lines were not built at all in any board or test. + + + +### Presubmit + +Every gerrit cl, if you did a dry-run or full run of the CQ will have coverage +results. They are slightly difficult to get to, but are very useful. + +On the "Checks" tab, find the build "firmware-zephyr-cov-cq" and open it. + + + +On the LUCI page, expand the "test firmware" step and click on "response". That +will show you a very basic summary of the coverage. + + + +For a detailed report, you can download the coverage report. Expand "try to +upload artifacts", then "upload artifacts", and click on "gs upload dir". + + + +From there, click on the download icon for the html.tbz2 file, and untar it +locally. Open lcov_rpt/index.html to view your results. + + + +### Post-submit + +If you are interested in the state of the world, not a specific CL, and the +coverage info in Code Search is not sufficient, you can download the coverage +report from the post-submit CQ build. + +Visit https://ci.chromium.org/p/chromeos/builders/postsubmit/firmware-zephyr-cov-postsubmit +and click on the latest successful build. + + -Example: -`zmake test --coverage test-drivers` -`genhtml -q -o build/zephyr/test-drivers/output/coverage_rpt/ build/zephyr/test-drivers/output/zephyr.info` +From there, it is exactly the same steps as above to get to the artifacts. diff --git a/docs/configuration/ap_power_sequencing.md b/docs/configuration/ap_power_sequencing.md index c5073d5809..ba9fc89f29 100644 --- a/docs/configuration/ap_power_sequencing.md +++ b/docs/configuration/ap_power_sequencing.md @@ -15,7 +15,7 @@ states (G3, S5, S3, S0, S0iX, etc). This includes the following tasks: The AP chipset options are grouped together in [config.h]. Select exactly one of the available AP chipset options (e.g. `CONFIG_CHIPSET_APOLLOLAKE`, -`CONFIG_CHIPSET_BRASWELL`, etc). If the AP chipset support is not available, +`CONFIG_CHIPSET_COMETLAKE`, etc). If the AP chipset support is not available, select `CONFIG_CHIPSET_ECDRIVEN` to enable basic support for handling S3 and S0 power states. diff --git a/docs/fingerprint/fingerprint-debugging.md b/docs/fingerprint/fingerprint-debugging.md index d098ca4427..84e5c13c9c 100644 --- a/docs/fingerprint/fingerprint-debugging.md +++ b/docs/fingerprint/fingerprint-debugging.md @@ -197,7 +197,7 @@ In your editor, specify the IP address and port for `gdbserver`: You will also want to provide the symbol files: * RW image: `build/<board>/RW/ec.RW.elf` -* RO image: `build/<board>/RO.ec.RO.elf` +* RO image: `build/<board>/RO/ec.RO.elf` Also, since we're compiling the firmware in the chroot, but your editor is running outside of the chroot, you'll want to remap the source code path to diff --git a/docs/fingerprint/fingerprint-dev-for-partners.md b/docs/fingerprint/fingerprint-dev-for-partners.md index e78fde5caa..20b89845aa 100644 --- a/docs/fingerprint/fingerprint-dev-for-partners.md +++ b/docs/fingerprint/fingerprint-dev-for-partners.md @@ -315,6 +315,11 @@ You can get a summary of the power over `N` seconds with: (chroot) $ dut-control -t N pp3300_dx_mcu_mv pp3300_dx_fp_mv pp1800_dx_fp_mv pp3300_dx_mcu_mw pp3300_dx_fp_mw pp1800_dx_fp_mw ``` +When measuring the power, make sure that any debuggers are disconnected. The +most reliable way to make sure it is disconnected is to physically disconnect +the debugger and servo_micro from the board. Then re-attach servo_micro and +restart `servod`. + <!-- mdformat off(b/139308852) --> *** note The `_mv` suffix denotes millivolt and `_mw` suffix denotes milliwatt. @@ -485,6 +490,8 @@ From the DUT, flash the firmware you copied: ![CQ Prototype Environment] +![FPMCU devboard environment v2 with satlab] + ## Troubleshooting ### Dragonclaw Rev 0.2 Rework {#dragonclaw-rev-0.2-rework} @@ -526,7 +533,7 @@ supply. (chroot) $ lsusb Bus 002 Device 003: ID 0897:0004 Lauterbach # ← This is my Lauterbach (debugger) -Bus 001 Device 013: ID 18d1:5002 Google Inc. # ← This is servo +Bus 001 Device 013: ID 18d1:5002 Google LLC # ← This is servo ``` ### "No servos found" when running servod @@ -601,3 +608,7 @@ Make sure that this interface is disabled: <!-- https://docs.google.com/drawings/d/1w2qbb4AsSxY-KTK2vXZ6TKeWHveWvS3Dkgh61ocu0wc --> [CQ Prototype Environment]: ../images/CQ_Prototype_Environment.jpg + +<!-- https://docs.google.com/drawings/d/13hsnPBa1aeMVU7CjrK1nz-aeYSQcdLxrylOEJNOiEA0 --> + +[FPMCU devboard environment v2 with satlab]: ../images/FPMCU_devboard_environment_v2_with_Satlab.jpg diff --git a/docs/fingerprint/fingerprint-factory-requirements.md b/docs/fingerprint/fingerprint-factory-requirements.md index 76b3ada517..5116b2c77a 100644 --- a/docs/fingerprint/fingerprint-factory-requirements.md +++ b/docs/fingerprint/fingerprint-factory-requirements.md @@ -474,7 +474,7 @@ sensor (in nocturne), not the FPC 1025 sensor (hatch). Convert the buffer in proprietary format into png: ```bash -(dut) $ /opt/fpc/fputils.py /tmp/fp.raw --png +(dut) $ /usr/local/opt/fpc/fputils.py /tmp/fp.raw --png Extraction found 2 images Wrote /tmp/fp.0.png (14085 bytes) Wrote /tmp/fp.1.png (14025 bytes) diff --git a/docs/fingerprint/fingerprint.md b/docs/fingerprint/fingerprint.md index 04f5a6bab9..8d4995a0fa 100644 --- a/docs/fingerprint/fingerprint.md +++ b/docs/fingerprint/fingerprint.md @@ -322,7 +322,8 @@ a lot easier during both development and testing. ## Power See [Measuring Power] for instructions on how to measure power with the -fingerprint development boards. +fingerprint development boards. *Make sure that any debuggers are completely +disconnected.* ### Dragonclaw v0.2 @@ -331,7 +332,7 @@ fingerprint development boards. ``` **Firmware Version**: -`bloonchipper_v2.0.4277-9f652bb3-RO_v2.0.7314-3dfc5ff6-RW.bin` +`bloonchipper_v2.0.4277-9f652bb3-RO_v2.0.14348-e5fb0b9-RW.bin` #### MCU is idle @@ -341,13 +342,13 @@ fingerprint development boards. ``` @@ NAME COUNT AVERAGE STDDEV MAX MIN -@@ sample_msecs 113 533.56 40.91 658.52 447.06 -@@ pp1800_dx_fp_mv 113 1800.00 0.00 1800.00 1800.00 -@@ pp1800_dx_fp_mw 113 0.00 0.00 0.00 0.00 -@@ pp3300_dx_fp_mv 113 3280.00 0.00 3280.00 3280.00 -@@ pp3300_dx_fp_mw 113 0.01 0.05 0.26 0.00 -@@ pp3300_dx_mcu_mv 113 3280.00 0.00 3280.00 3280.00 -@@ pp3300_dx_mcu_mw 113 24.67 0.00 24.67 24.67 +@@ sample_msecs 478 125.49 26.02 431.96 92.23 +@@ pp1800_dx_fp_mv 478 1800.00 0.00 1800.00 1800.00 +@@ pp1800_dx_fp_mw 478 0.00 0.00 0.00 0.00 +@@ pp3300_dx_fp_mv 478 3280.00 0.00 3280.00 3280.00 +@@ pp3300_dx_fp_mw 478 0.00 0.03 0.26 0.00 +@@ pp3300_dx_mcu_mv 478 3280.00 0.00 3280.00 3280.00 +@@ pp3300_dx_mcu_mw 478 21.78 0.06 23.09 21.78 ``` #### MCU in low power mode (suspend) @@ -358,13 +359,13 @@ fingerprint development boards. ``` @@ NAME COUNT AVERAGE STDDEV MAX MIN -@@ sample_msecs 115 526.56 36.79 607.60 426.58 -@@ pp1800_dx_fp_mv 115 1800.00 0.00 1800.00 1800.00 -@@ pp1800_dx_fp_mw 115 0.00 0.00 0.00 0.00 -@@ pp3300_dx_fp_mv 115 3287.30 2.25 3288.00 3280.00 -@@ pp3300_dx_fp_mw 115 0.00 0.02 0.26 0.00 -@@ pp3300_dx_mcu_mv 115 3280.97 2.62 3288.00 3280.00 -@@ pp3300_dx_mcu_mw 115 4.02 0.64 10.76 3.94 +@@ sample_msecs 488 122.99 26.37 458.47 92.69 +@@ pp1800_dx_fp_mv 488 1800.00 0.00 1800.00 1800.00 +@@ pp1800_dx_fp_mw 488 0.00 0.00 0.00 0.00 +@@ pp3300_dx_fp_mv 488 3287.79 1.29 3288.00 3280.00 +@@ pp3300_dx_fp_mw 488 0.01 0.04 0.26 0.00 +@@ pp3300_dx_mcu_mv 488 3283.38 3.95 3288.00 3280.00 +@@ pp3300_dx_mcu_mw 488 1.57 0.59 9.73 1.31 ``` ### Icetower v0.1 @@ -385,7 +386,7 @@ measure releases before that point. ``` **Firmware Version**: -`dartmonkey_v2.0.2887-311310808-RO_v2.0.7304-441100b93-RW.bin` +`dartmonkey_v2.0.2887-311310808-RO_v2.0.14340-6c1587ca7-RW.bin` #### MCU is idle @@ -395,11 +396,11 @@ measure releases before that point. ``` @@ NAME COUNT AVERAGE STDDEV MAX MIN -@@ sample_msecs 178 337.13 20.91 404.32 289.82 -@@ pp3300_dx_fp_mv 178 3256.00 0.00 3256.00 3256.00 -@@ pp3300_dx_fp_mw 178 0.00 0.00 0.00 0.00 -@@ pp3300_dx_mcu_mv 178 3248.00 0.00 3248.00 3248.00 -@@ pp3300_dx_mcu_mw 178 45.17 0.09 45.21 44.95 +@@ sample_msecs 523 114.85 18.33 386.55 88.95 +@@ pp3300_dx_fp_mv 523 3256.00 0.00 3256.00 3256.00 +@@ pp3300_dx_fp_mw 523 0.00 0.00 0.00 0.00 +@@ pp3300_dx_mcu_mv 523 3248.00 0.00 3248.00 3248.00 +@@ pp3300_dx_mcu_mw 523 43.86 0.10 43.91 43.65 ``` #### MCU in low power mode (suspend) @@ -410,11 +411,11 @@ measure releases before that point. ``` @@ NAME COUNT AVERAGE STDDEV MAX MIN -@@ sample_msecs 174 345.60 31.93 457.62 283.00 -@@ pp3300_dx_fp_mv 174 3264.00 0.00 3264.00 3264.00 -@@ pp3300_dx_fp_mw 174 0.00 0.00 0.00 0.00 -@@ pp3300_dx_mcu_mv 174 3260.69 3.94 3264.00 3256.00 -@@ pp3300_dx_mcu_mw 174 5.47 0.10 5.48 4.17 +@@ sample_msecs 501 119.79 14.72 381.92 89.22 +@@ pp3300_dx_fp_mv 501 3256.00 0.00 3256.00 3256.00 +@@ pp3300_dx_fp_mw 501 0.00 0.00 0.00 0.00 +@@ pp3300_dx_mcu_mv 501 3256.00 0.00 3256.00 3256.00 +@@ pp3300_dx_mcu_mw 501 5.74 0.28 11.98 5.73 ``` ## ChromeOS Build (portage / ebuild) diff --git a/docs/gitlab.md b/docs/gitlab.md new file mode 100644 index 0000000000..9f8d07ceec --- /dev/null +++ b/docs/gitlab.md @@ -0,0 +1,84 @@ +# Gitlab CI + +The Zephyr EC Test Team uses external Gitlab CI jobs to generate code coverage +reports. These CI jobs are defined in the `.gitlab-ci.yml` file in +`platform/ec`. + +[TOC] + +## Running CI jobs locally + +For development purposes, it is possible to run the CI jobs on a local machine +using Docker and `gitlab-runner`. + +Note: not all features of Gitlab CI are available when running builds locally. +For example, the local runner cannot build dependencies specified in the +`needs:` sections. (But you can run jobs individually). More details can be +found in the [`gitlab-runner` docs] +(https://docs.gitlab.com/runner/commands/#limitations-of-gitlab-runner-exec). + +### Installation + +First, you must [install Docker](https://docs.docker.com/get-docker/) on your +system. This is out of the scope of this guide, but there are many resources +on the Internet describing how to do this. Docker allows the CI jobs to run in a +controlled environment using containers, ensuring that the jobs run consistently +and without needing to pollute your own system with the many dependencies. + +Next, install the Gitlab Runner. This application is able interpret the +`.gitlab-ci.yml` file, spawn Docker containers to run jobs, and report back +results and artifacts. Usually, runners are deployed in fleets and configured to +register with a Gitlab server, which can push CI jobs to individual runners to +execute. However, it is also possible to use the runner in a purely local mode +using `gitlab-runner exec`. + +Full instructions are available on the +[Gitlab website](https://docs.gitlab.com/runner/install/), but the fastest way +to get it for Debian-based systems is to download and install the package +directly: + +``` +wget https://gitlab-runner-downloads.s3.amazonaws.com/latest/deb/gitlab-runner_amd64.deb +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 + +``` +(outside) +mkdir ~/gitlab-runner-output # Do once + +cd ~/chromiumos/src/platform/ec +sudo gitlab-runner exec docker \ + --docker-volumes "$HOME/chromiumos/:$HOME/chromiumos/" \ + --docker-volumes "$HOME/gitlab-runner-output:/builds" \ + <name of job> +``` + +Please note: + * `$HOME/chromiumos` should be adjusted to wherever your tree is checked out + to. The reason it is necessary to mount the entire source tree to the + Docker container (as opposed to just `platform/ec`, which is done + automatically) is because the runner needs access to the Git database in + order to clone the source code. Because the `platform/ec` repository is + governed by the `repo` tool, the Git database is actually located at + `$HOME/chromiumos/.repo/projects/src/platform/ec.git`. (The `.git` directory + in `platform/ec` is merely a symlink) + * The second mount causes the runner's work directory to be backed by a + directory on your own system so that you can examine the artifacts after the + job finishes and the container is stopped. + * `<name of job>` is one of the jobs defined in `.gitlab-ci.yml`, such as + `twister_coverage`. + * You may see error messages like `ERROR: Could not create cache adapter`. + These appear to be benign, although getting the cache to work might improve + subsequent build times. This may be investigated at a later date. + +### Accessing Artifacts + +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. diff --git a/docs/ide-support.md b/docs/ide-support.md index cec196be58..1a8abda422 100644 --- a/docs/ide-support.md +++ b/docs/ide-support.md @@ -1,5 +1,7 @@ # IDE Support +This document explains how to configure IDEs to better support the EC codebase. + [TOC] ## Odd File Types @@ -12,16 +14,17 @@ Patterns | Vague Type ----------------------------------------------------- | ---------- `README.*` | Text `Makefile.rules`, `Makefile.toolchain` | Makefile +`Makefile.ide` | Makefile `gpio.wrap` | C Header `gpio.inc` | C Header `*.tasklist`, `*.irqlist`, `*.mocklist`, `*.testlist` | C Header ## IDE Configuration Primitives -Due to the way most EC code has been structured, you can typically only safely -inspect a configuration for a single image (RO or RW) for a single board. Thus, -you need to specify the specific board/image pair when requesting defines and -includes. +EC firmware presents some unique challenges because it is designed to support a +number of different MCUs and board configurations, each of which is split across +separate RO (Read-Only) and RW (Read-Write) applications. For this reason, you +must specify the specific board/image pair when requesting defines and includes. Command | Description -------------------------------------------- | ------------------------------ @@ -36,8 +39,11 @@ includes selectable sub-configurations for every board/image pair. 1. From the root `ec` directory, do the following: ```bash - mkdir -p .vscode - ./util/ide-config.sh vscode all:RW all:RO | tee .vscode/c_cpp_properties.json + (outside) $ mkdir -p .vscode + ``` + + ```bash + (chroot) $ ./util/ide-config.sh vscode all:RW all:RO | tee .vscode/c_cpp_properties.json ``` 2. Open VSCode and navigate to some C source file. @@ -53,5 +59,63 @@ includes selectable sub-configurations for every board/image pair. to copy the default settings to `.vscode/settings.json`: ```bash - cp .vscode/settings.json.default .vscode/settings.json + (outside) $ cp .vscode/settings.json.default .vscode/settings.json + ``` + +## VSCode CrOS IDE + +CrOS IDE is a VSCode extension to enable code completion and navigation for +ChromeOS source files. + +Support for `platform/ec` is not available out of the box (yet), but can be +manually enabled following these steps. + +### Prerequisites + +Install CrOS IDE following the [quickstart guide] + +<!-- mdformat off(b/139308852) --> +*** note +NOTE: CrOS IDE uses the VSCode extension `clangd` for code completion and +navigation. The installation of CrOS IDE disables the built-in +`C/C++ IntelliSense` because it is not compatible with `clangd`. +*** +<!-- mdformat on --> + +### Configure EC Board + +1. Enter the EC repository: + + ```bash + (chroot) $ cd ~/chromiumos/src/platform/ec ``` + +1. Create a `compile_commands.json` for the all EC boards: + + ```bash + (chroot) $ make all-ide-compile-cmds -j + ``` + +1. Select a particular board: + + ```bash + (chroot) $ export BOARD=bloonchipper + ``` + +1. Copy the new `compile_commands.json` in the root of the EC repository: + + ```bash + cp build/${BOARD}/RW/compile_commands.json . + ``` + +Note: a single `compile_commands.json` can only cover one specific build +configuration. Only the `compile_commands.json`placed in the root of the EC +repository is considered active. When the build configuration changes (e.g. user +wants to use a different board), repeat steps 3 and 4 to replace the active +`compile_commands.json` file. + +To create a `compile_commands.json` for a specific EC board: + +```bash +(chroot) $ make BOARD=${BOARD} ide-compile-cmds +``` diff --git a/docs/images/CQ_Prototype_Environment.jpg b/docs/images/CQ_Prototype_Environment.jpg Binary files differindex 77b39d9470..192fe139fe 100644 --- a/docs/images/CQ_Prototype_Environment.jpg +++ b/docs/images/CQ_Prototype_Environment.jpg diff --git a/docs/images/FPMCU_devboard_environment_v2_with_Satlab.jpg b/docs/images/FPMCU_devboard_environment_v2_with_Satlab.jpg Binary files differnew file mode 100644 index 0000000000..c3663f7401 --- /dev/null +++ b/docs/images/FPMCU_devboard_environment_v2_with_Satlab.jpg diff --git a/docs/images/artifacts.png b/docs/images/artifacts.png Binary files differnew file mode 100644 index 0000000000..2981509362 --- /dev/null +++ b/docs/images/artifacts.png diff --git a/docs/images/dir_coverage.png b/docs/images/dir_coverage.png Binary files differnew file mode 100644 index 0000000000..152b2711a2 --- /dev/null +++ b/docs/images/dir_coverage.png diff --git a/docs/images/download_html.png b/docs/images/download_html.png Binary files differnew file mode 100644 index 0000000000..399d098936 --- /dev/null +++ b/docs/images/download_html.png diff --git a/docs/images/file_coverage.png b/docs/images/file_coverage.png Binary files differnew file mode 100644 index 0000000000..f110e44200 --- /dev/null +++ b/docs/images/file_coverage.png diff --git a/docs/images/gerrit_coverage_links.png b/docs/images/gerrit_coverage_links.png Binary files differnew file mode 100644 index 0000000000..43afac943e --- /dev/null +++ b/docs/images/gerrit_coverage_links.png diff --git a/docs/images/postsubmit.png b/docs/images/postsubmit.png Binary files differnew file mode 100644 index 0000000000..65c630276f --- /dev/null +++ b/docs/images/postsubmit.png diff --git a/docs/images/test_firmware.png b/docs/images/test_firmware.png Binary files differnew file mode 100644 index 0000000000..42f707810a --- /dev/null +++ b/docs/images/test_firmware.png diff --git a/docs/ite-ec-reflashing.md b/docs/ite-ec-reflashing.md new file mode 100644 index 0000000000..59cfc8f303 --- /dev/null +++ b/docs/ite-ec-reflashing.md @@ -0,0 +1,194 @@ +# ITE EC firmware reflashing via Servo: How it works + +This doc: [http://go/cros-ite-reflash-design](https://goto.google.com/cros-ite-ec-reflash-design) +<br> +First written: 2022-08-15 +<br> +Last updated: 2022-08-24 + +Familiarity with [Chromium OS](https://www.chromium.org/chromium-os) and +[Embedded Controller (EC)](../README.md) development is assumed. + +[TOC] + +## Background + +### Other documents +* [Reflashing an ITE EC](../util/iteflash.md) +* Googlers, and Partners involved in ITE EC projects only: + [The State of ITE CrOS EC Reflashing](https://goto.google.com/cros-ite-ec-reflash-state) + * That document is not public, do not request access if you lack it. +* `i2c-pseudo` [README](../extra/i2c_pseudo/README) +* `i2c-pseudo` [Documentation.txt](../extra/i2c_pseudo/Documentation.txt) + +### Terminology + +**EC** refers to an +[Embedded Controller](https://en.wikipedia.org/wiki/Embedded_controller) +(microcontroller). + +**ITE EC** refers to the [ITE](http://www.ite.com.tw/) +[IT8320](http://www.ite.com.tw/en/product/view?mid=96) +[Embedded Controller (EC)](https://en.wikipedia.org/wiki/Embedded_controller) +microcontroller when used as a Chromium OS / Chrome OS EC. + +**CrOS** refers to Chromium OS, Chrome OS, or both, depending on the context. +The distinction between Chromium OS and Chrome OS is largely immaterial to this +document. + +**DUT Controller Servo** refers to a device that provides direct access +to various circuits on a Chrome OS device motherboard. As of this writing, the +most common DUT controller [servos](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/main/docs/servo.md) used by +CrOS developers are +[CR50 (CCD)](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/main/docs/ccd.md), +`C2D2`, +[Servo Micro](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/main/docs/servo_micro.md), and +[Servo v2](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/main/docs/servo_v2.md). (Note that +[Servo v4](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/main/docs/servo_v4.md) and +[Servo v4.1](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/main/docs/servo_v4p1.md) are **not** +DUT Controller Servos. They are Hub Servos, and are typically used in conjection with a DUT Controller Servo. Hub Servos are not directly involved in EC reflashing.) See also +[Case-Closed Debug in Chromebooks and Servo Micro](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/main/board/servo_micro/ccd.md). + +**Servod** refers to a piece of software that runs on a USB host and provides +interfaces for controlling a Servo connected to the host as a USB device. See [servod](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/main/docs/servod.md). + +## Core steps + +Two things need to happen: + +1. Send special non-I2C waveforms over I2C clock and data lines to the ITE EC, + to enable a debug mode in the EC where it will respond at a predefined + I2C address as an I2C peripheral. + * This debug mode is implemented by ITE in silicon and/or immutable + firmware, it is not part of Chrome OS EC firmware. It is available even + if Chrome OS RO+RW firmware on the EC is corrupted. + +1. Communicate with and control the ITE EC using its I2C-based debug mode. All + signals on the I2C bus in question are now actual I2C, with the ITE EC + acting as an I2C peripheral device. The EC firmware gets sent as I2C + payload. + * If the previous step is not successful, then the EC will not respond to + I2C messages. + +The DUT Controller Servo performs these steps. + +## Control flow + +[flash_ec](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/util/flash_ec) +is the user interface for all Chrome OS device EC reflashing via Servos. +`servod` must be running to use `flash_ec`. + +### Original control flow, for Servo v2 only + +The original implementation of ITE EC reflashing via Servo is only compatible +with Servo v2, due to interfacing directly with its FTDI USB to MPSSE IC +(FTDI FT4232HL). + +1. `flash_ec` tells `servod` to close its interface for controlling the + `Servo v2` FTDI USB device. + * This breaks the layering of `servod` as the interface through which + servos are controlled, and is a maintenance + complexity burden to + support in `servod`. No other servo I2C interfaces in `servod` support or + need this functionality of relinquishing control. +1. `flash_ec` invokes [iteflash](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/main/util/iteflash.c). +1. `iteflash` takes control of the `Servo v2` FTDI USB device. +1. `iteflash` [bit-bangs](https://en.wikipedia.org/wiki/Bit_banging) the + special waveforms using the `Servo v2` FTDI USB device. +1. `iteflash` uses FTDI I2C functionality (not bit-banging) to talk I2C with + the ITE EC, including sending the EC firmware as payload in I2C messages. +1. `flash_ec` tells `servod` to reopen its `Servo v2` FTDI USB interface. + +### New control flow through servod, for all other DUT controller servo types + +1. When `servod` starts, it creates a pseudo I2C adapter in Linux for every + servo I2C bus it controls, if the `i2c-pseudo` module is loaded. + * This pseudo I2C adapter can be used on the host system as if it were a + native I2C bus, including from userspace if the `i2c-dev` module is + loaded. + * For more information on the `i2c-pseudo` module see + [Reflashing an ITE EC](../util/iteflash.md), as well as `i2c-pseudo`'s + [README](../extra/i2c_pseudo/README) and + [Documentation.txt](../extra/i2c_pseudo/Documentation.txt). +1. `flash_ec` issues a `servod` command for the DUT controller servo to send + the special waveforms. + * For `Servo Micro` and `C2D2` all `servod` needs to do is issue a + servo console command, `enable_ite_dfu`, which triggers a + servo firmware function to perform the special waveforms. + * The servo does not know what kind of DUT it is connected to, thus the + `enable_ite_dfu` console commands are always available. The + special waveforms will not do anything useful unless the DUT has + an ITE EC. + * `CR50` (CCD) is mostly the same, except: + 1. CCD must be unlocked and the `ccd_i2c_en` CCD capability must be set + to `Always`. + 1. The `CR50` firmware function for sending the special waveforms is + invoked by a special I2C message, not a console command. + 1. `CR50` must reboot itself to perform the special waveforms. During + normal operation `CR50` has deliberate clock jitter which would + prevent accurately preforming the waveforms. This jitter cannot + safely be disabled, except on reset, and only while the `AP` is held + in reset. + * [Future] If we were to support this control flow with `Servo v2`, the + cleanest way would be to move the FTDI-based bit-banging of the + special waveforms from `iteflash` into `servod` itself, as a C/C++ + extension, so that `flash_ec` can trigger it with a `servod` command the + same as for other servo types. This would allow removing the hack in + `servod` to relinquish control of the `Servo v2` FTDI USB interface. + * Proof-of-concept [CL:1522847](https://crrev.com/c/1522847) adds support + for using Servo v2 via `servod`. However as of this writing that CL + ([patchset 14](https://crrev.com/c/1522847/14)) only changes the I2C + communication path, it does NOT move the special waveforms into + `servod`, which is needed to remove the `servod` I2C interface + close + reopen hack and fully merge the Servo v2 ITE EC reflashing into + this new control flow. +1. `flash_ec` asks `servod` for the local Linux i2c-dev path of the + DUT Controller Servo's DUT-connected I2C interface (which is backed by + `servod` itself via the `i2c-pseudo` module). +1. `flash_ec` invokes `iteflash`, passing it the i2c-dev path given by + `servod`. +1. `iteflash` performs the EC firmware update via the i2c-dev interface. + +## Why `i2c-pseudo` and alternative implementations considered + +Instead of using `i2c-dev` Linux I2C interfaces, `iteflash` could communicate +directly with `servod` using a custom protocol. This would make `iteflash` +dependent on `servod` and whatever custom protocol we come up with, as there is +no standard userspace<->userspace I2C interface to implement. + +In the future we may choose to implement Servo I2C interfaces as actual +host-side Linux drivers, which `servod` would use via `i2c-dev` +(which it supports already!). Since the `flash_ec` and `iteflash` portions of +this process are built around `i2c-dev` now, they should continue working with +no changes needed for this scenario. + +Why bother with i2c-pseudo at all then? Why not go straight to reimplementing +the Servo I2C interfaces as new Linux I2C adapter drivers, instead of +implementing the new `i2c-pseudo` driver? + +Rearchitecting the Servo I2C interfaces is not something to be considered +lightly, and not worthwhile just for ITE EC reflashing. By staying with the +existing `servod` Servo I2C implementations we have not introduced any +dependency on new kernel modules for *existing* `servod` functionality. Only +the new ITE EC reflashing functionality depends on `i2c-pseudo`. As with +`i2c-pseudo` we would need to rely on out-of-tree kernel module distribution +for these new Servo I2C modules until eventual upstream acceptance + +percolation down to distribution Linux kernels, with no guarantee of acceptance +for our obscure Servo hardware. Depending on a new kernel module for this one +new function of ITE EC reflashing is one thing. Requiring new modules for all +`servod` use would be quite another. Realistically we would need to maintain +fallback code in `servod` to use its existing internal Servo I2C interface +implementations when the kernel ones aren't available, but that has a +maintenance cost too. These same issues would be faced with every new +generation of Servo, so this broad Servo + `servod` architectural change is not +something to be considered lightly or just for ITE EC reflashing. + +`i2c-pseudo` has potential uses in the CrOS ecosystem beyond ITE EC reflashing. +A big one is mocking I2C interfaces for driver and system tests. There is the +longstanding `i2c-stub` module for this purpose, but its functionality is +limited compared to `i2c-pseudo`, not all I2C device behavior can be modeled +with `i2c-stub`. Also by having the `servod` I2C pseudo interfaces, one can +conveniently use the standard Linux I2C command line tools +(i2cget(8), i2cset(8), i2ctransfer(8), etc) for interfacing with Servo and DUT +I2C devices. While it is unlikely that i2c-pseudo will have any use in CrOS +itself, it is expected to have further uses in both developer tooling and +code tests. diff --git a/docs/reducing_ec_image_size.md b/docs/reducing_ec_image_size.md index 5e09c99e51..58ed66e25c 100644 --- a/docs/reducing_ec_image_size.md +++ b/docs/reducing_ec_image_size.md @@ -175,13 +175,13 @@ prj.conf file to disable the console command. | | CONFIG_CMD_CHGRAMP | `chgramp` | | | | CONFIG_CMD_CLOCKGATES | `clockgates` | | | | CONFIG_CMD_COMXTEST | `comxtest` | | -| x | CONFIG_CMD_CRASH | `crash` | | +| x | CONFIG_CMD_CRASH | `crash` | Used by TAST `crash.ECCrash`, FAFT `firmware_ECSharedMem` | | | CONFIG_CMD_DEVICE_EVENT | `deviceevent` | | | | CONFIG_CMD_DLOG | `dlog` | | | | CONFIG_CMD_ECTEMP | `ectemp` | | | | CONFIG_CMD_FASTCHARGE | `fastcharge` | Obsolete? use CONFIG_CMD_CHARGER_PROFILE_OVERRIDE? | | | CONFIG_CMD_FLASH | `flasherase`<br>`flashwrite`<br>`flashread` | | -| | CONFIG_CMD_FLASHINFO | `flashinfo` | | +| x | CONFIG_CMD_FLASHINFO | `flashinfo` | Used by TAST `firmware.ECSize` | | | CONFIG_CMD_FLASH_TRISTATE | `fpcapture`<br>`flash_tristate` | | | | CONFIG_CMD_FLASH_WP | `flashwp` | | | | CONFIG_CMD_FORCETIME | `forcetime` | | @@ -208,14 +208,14 @@ prj.conf file to disable the console command. | | CONFIG_CMD_IDLE_STATS | `idlestats` | | | | CONFIG_CMD_INA | `ina` | | | | CONFIG_CMD_JUMPTAGS | `jumptags` | | -| x | CONFIG_CMD_KEYBOARD | `8042`<br>`ksstate`<br>`kbpress` | | +| x | CONFIG_CMD_KEYBOARD | `8042`<br>`ksstate`<br>`kbpress` | Used by `firmware_ECKeyboard` | | | CONFIG_CMD_LEDTEST | `ledtest` | | | | CONFIG_CMD_MCDP | `mcdp` | | | | CONFIG_CMD_MD | `md` | | | | CONFIG_CMD_MEM | | Not a console command - gates `md` and `rw` | | | CONFIG_CMD_MFALLOW | `mfallow` | | | | CONFIG_CMD_MMAPINFO | `mmapinfo` | | -| x | CONFIG_CMD_PD | `pd` | Used by FAFT PD | +| x | CONFIG_CMD_PD | `pd` | Used by FAFT PD, TAST `firmware.ECSystemLocked` | | | CONFIG_CMD_PD_DEV_DUMP_INFO | | Not a console command | | | CONFIG_CMD_PD_FLASH | `pd flash` | Not supported by TCPMv2 | | | CONFIG_CMD_PD_SRCCAPS_REDUCED_SIZE | `pd <port> srccaps` | Defining this reduces the verbosity of this command, saving bytes | @@ -347,13 +347,14 @@ Disable all debug from ASSERT() calls.<br> EC is reset using a software breakpoi It is not recommended to disable `CONFIG_PLATFORM_EC_DEBUG_ASSERT_REBOOTS` on shipping firmware. -### Disable console help +### Disable console help and history The help strings can be removed from the final build, saving about 5000 bytes of -flash space. +flash space. The history command can also be disabled to save another 200 bytes +of flash space. -For cros-ec builds, add `#undef CONFIG_CONSOLE_CMDHELP` to the -board.h/baseboard.h file. +For cros-ec builds, add `#undef CONFIG_CONSOLE_CMDHELP` and `#undef +CONFIG_CONSOLE_HISTORY` to the board.h/baseboard.h file. zephyr-ec builds use Zephyr's shell subsystem and by default enable the `CONFIG_SHELL_MINIMAL` option. This option already disables shell help along diff --git a/docs/zephyr/README.md b/docs/zephyr/README.md index ded31b8d6d..3b8b8dc05e 100644 --- a/docs/zephyr/README.md +++ b/docs/zephyr/README.md @@ -26,6 +26,9 @@ new project variant. The [Zephyr New Board Checklist](zephyr_new_board_checklist.md) links to the documentation needed to configure individual EC features. +The [Zephyr Troubleshooting](zephyr_troubleshooting.md) page lists few common +errors and troubleshooting techniques used when working with Zephyr. + ## Source Code Organization Zephyr EC images rely on multiple Chromium repositories to build Zephyr EC images. @@ -119,4 +122,4 @@ The following provides an overview of the sub-directories found under [`third_party/zephyr/main`]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/third_party/zephyr/main [`third_party/zephyr/cmsis`]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/third_party/zephyr/cmsis [`platform/ec`]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec -[`ec_app_main()`]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/app/ec/ec_app_main.c
\ No newline at end of file +[`ec_app_main()`]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/app/ec/ec_app_main.c diff --git a/docs/zephyr/project_config.md b/docs/zephyr/project_config.md index f12d47ba36..f930908502 100644 --- a/docs/zephyr/project_config.md +++ b/docs/zephyr/project_config.md @@ -112,7 +112,7 @@ This file, should at minimum contain the following: ``` cmake cmake_minimum_required(VERSION 3.20.1) -find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) +find_package(Zephyr REQUIRED HINTS "${ZEPHYR_BASE}") project(ec) ``` @@ -148,7 +148,7 @@ 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. +# 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. diff --git a/docs/zephyr/zephyr_adc.md b/docs/zephyr/zephyr_adc.md index c57f4bd3a6..0511668517 100644 --- a/docs/zephyr/zephyr_adc.md +++ b/docs/zephyr/zephyr_adc.md @@ -8,19 +8,11 @@ ## Kconfig Options -Kconfig Option | Default state | Documentation -:--------------------------------- | :------------ | :------------ -`CONFIG_PLATFORM_EC_ADC` | Enabled | [EC ADC] +The [`CONFIG_ADC`] option enables ADC support in the Zephyr EC application. +Use the [`CONFIG_ADC_SHELL`] option to enable ADC related shell commands. -The following options are available only when `CONFIG_PLATFORM_EC_ADC=y`. - -Kconfig sub-option | Default | Documentation -:----------------------------------------------- | :-----: | :------------ -`CONFIG_ADC_SHELL` | n | [CONFIG_ADC_SHELL] -`CONFIG_PLATFORM_EC_ADC_CMD` | y | [ADC cmd] -`CONFIG_PLATFORM_EC_ADC_RESOLUTION` | 10 | [ADC resolution] -`CONFIG_PLATFORM_EC_ADC_OVERSAMPLING` | 0 | [ADC oversampling] -`CONFIG_PLATFORM_EC_ADC_CHANNELS_RUNTIME_CONFIG` | n | [ADC runtime config] +Refer to [Kconfig.adc] for all sub-options related to ADC support that are +specific to the Zephyr EC application. ## Devicetree Nodes @@ -56,7 +48,6 @@ enumeration and the Zephyr ADC driver's channel_id. named-adc-channels { compatible = "named-adc-channels"; vbus { - label = "VBUS"; enum-name = "ADC_VBUS"; io-channels = <&adc0 1>; /* Measure VBUS through a 1/10 voltage divider */ @@ -158,22 +149,18 @@ named-adc-channels { compatible = "named-adc-channels"; adc_charger: charger { - label = "TEMP_CHARGER"; enum-name = "ADC_TEMP_SENSOR_CHARGER"; io-channels = <&adc0 0>; }; adc_pp3300_regulator: pp3300_regulator { - label = "TEMP_PP3300_REGULATOR"; enum-name = "ADC_TEMP_SENSOR_PP3300_REGULATOR"; io-channels = <&adc0 1>; }; adc_ddr_soc: ddr_soc { - label = "TEMP_DDR_SOC"; enum-name = "ADC_TEMP_SENSOR_DDR_SOC"; io-channels = <&adc0 8>; }; adc_fan: fan { - label = "TEMP_FAN"; enum-name = "ADC_TEMP_SENSOR_FAN"; io-channels = <&adc0 3>; }; @@ -182,17 +169,10 @@ named-adc-channels { [ADC]: ../ec_terms.md#adc [ADC Example]: ../images/volteer_adc.png -[EC ADC]: -https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.adc?q=%22menuconfig%20PLATFORM_EC_ADC%22&ss=chromiumos -[CONFIG_ADC_SHELL]: +[Kconfig.adc]: ../../zephyr/Kconfig.adc +[`CONFIG_ADC`]: +https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_ADC +[`CONFIG_ADC_SHELL`]: https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_ADC_SHELL -[ADC cmd]: -https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.adc?q=%22config%20PLATFORM_EC_ADC_CMD%22&ss=chromiumos -[ADC resolution]: -https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.adc?q=%22config%20PLATFORM_EC_ADC_RESOLUTION%22&ss=chromiumos -[ADC oversampling]: -https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.adc?q=%22config%20PLATFORM_EC_ADC_OVERSAMPLING%22&ss=chromiumos -[ADC runtime config]: -https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.adc?q=%22config%20PLATFORM_EC_ADC_CHANNELS_RUNTIME_CONFIG%22&ss=chromiumos [named-adc.yaml]: ../../zephyr/dts/bindings/adc/named-adc.yaml diff --git a/docs/zephyr/zephyr_battery.md b/docs/zephyr/zephyr_battery.md index c84bcc3b8e..3dde8cb9cf 100644 --- a/docs/zephyr/zephyr_battery.md +++ b/docs/zephyr/zephyr_battery.md @@ -86,7 +86,7 @@ named-i2c-ports { battery { i2c-port = <{i2c_phandle}>; remote-port = <{I2C_PASSTHRU-PORT-NUMBER}>; - enum-name = "I2C_PORT_BATTERY"; + enum-names = "I2C_PORT_BATTERY"; }; ... ... diff --git a/docs/zephyr/zephyr_bc12.md b/docs/zephyr/zephyr_bc12.md index 6fffc16358..a7f3431829 100644 --- a/docs/zephyr/zephyr_bc12.md +++ b/docs/zephyr/zephyr_bc12.md @@ -18,9 +18,14 @@ sub-options related to BC1.2 support. ## Devicetree Nodes -A BC1.2 device node should be child of an USBC port node with a compatible -property equals to "named-usbc-port". The USBC port node should have only one -BC1.2 device node. +The BC1.2 device node is added to the I2C bus node, and the bc12 property on +the USBC port node refers to the BC1.2 device. + +### Richtek RT1718S + +There are two nodes describing the Richtek RT1718, one for BC1.2 +[richtek,rt1718-bc12.yaml] and one for TCPC[richtek,rt1718s-tcpc.yaml]. The node +for the TCPC contains information about I2C bus and address. ### Richtek RT1739 @@ -58,15 +63,6 @@ found in [shimmed_task_id.h]. Example of defining a BC1.2 chip in DTS: ``` -named-i2c-ports { - compatible = "named-i2c-ports"; - ... - c0_bc12: c0_bc12 { - i2c-port = <&i2c0_0>; - enum-name = "I2C_PORT_USB_C0_BC12"; - }; -}; - gpio-interrupts { compatible = "cros-ec,gpio-interrupts" int_usb_c0_bc12: usb_c0_bc12 { @@ -76,23 +72,26 @@ gpio-interrupts { }; }; +&i2c2_0 { + bc12_port0: pi3usb9201@5f { + compatible = "pericom,pi3usb9201"; + status = "okay"; + reg = <0x5f>; + irq = <&int_usb_c0_bc12>; + }; +}; + port0@0 { compatible = "named-usbc-port"; reg = <0>; - bc12 { - compatible = "pericom,pi3usb9201"; - status = "okay"; - irq = <&int_usb_c0_bc12>; - port = <&c0_bc12>; - i2c-addr-flags = "PI3USB9201_I2C_ADDR_3_FLAGS"; - }; + bc12 = <&bc12_port0>; }; ``` -`bc12` is a BC1.2 device node ("pericom,pi3usb9201" is a compatible that is -used by one of the BC1.2 devices). The `bc12` is child of the `port0@0` which -has to be the "named-usbc-port". Each "named-usbc-port" can have no more than -one BC1.2 device node. +`bc12_port0` is a BC1.2 device node ("pericom,pi3usb9201" is a compatible that +is used by one of the BC1.2 devices). The `bc12_port0` is child of the `i2c2_0` +which is an I2C controller device. Each "named-usbc-port" node can point one +BC1.2 device node. [Kconfig.usb_charger]: https://source.chromium.org/chromium/chromiumos/platform/ec/+/HEAD:zephyr/Kconfig.usb_charger [richtek,rt1739-bc12.yaml]: https://source.chromium.org/chromium/chromiumos/platform/ec/+/HEAD:zephyr/dts/bindings/usbc/richtek,rt1739-bc12.yaml diff --git a/docs/zephyr/zephyr_build.md b/docs/zephyr/zephyr_build.md index 8668c50e11..a80fe06d98 100644 --- a/docs/zephyr/zephyr_build.md +++ b/docs/zephyr/zephyr_build.md @@ -38,7 +38,7 @@ For example, to build the EC for `skyrim`, run: (chroot) $ zmake build skyrim ``` -The output binary will then be located at `build/zephyr/skyrim/output/zephyr.bin`. +The output binary will then be located at `build/zephyr/skyrim/output/ec.bin`. Additional output files you may find useful: diff --git a/docs/zephyr/zephyr_charger.md b/docs/zephyr/zephyr_charger.md index 3857571ad2..8bb4f8d3f5 100644 --- a/docs/zephyr/zephyr_charger.md +++ b/docs/zephyr/zephyr_charger.md @@ -56,7 +56,7 @@ named-i2c-ports { /* TODO(b/228237412): Update this comment once charger chg_chips[] is * created by a shim driver. */ - enum-name = "I2C_PORT_CHARGER"; + enum-names = "I2C_PORT_CHARGER"; }; }; ``` diff --git a/docs/zephyr/zephyr_eeprom.md b/docs/zephyr/zephyr_eeprom.md index f18669fd75..9bc2f8b092 100644 --- a/docs/zephyr/zephyr_eeprom.md +++ b/docs/zephyr/zephyr_eeprom.md @@ -41,7 +41,6 @@ An example definition of the Atmel AT24 is: cbi_eeprom: eeprom@50 { compatible = "atmel,at24"; reg = <0x50>; - label = "EEPROM_CBI"; size = <2048>; pagesize = <16>; address-width = <8>; diff --git a/docs/zephyr/zephyr_gpio.md b/docs/zephyr/zephyr_gpio.md index 5e70562ab9..5204e6107f 100644 --- a/docs/zephyr/zephyr_gpio.md +++ b/docs/zephyr/zephyr_gpio.md @@ -70,6 +70,15 @@ included from the main board DTS file. For platform specific features, other flags may be available in the Zephyr [dt-bindings/gpio/gpio.h] file, such as `GPIO_VOLTAGE_1P8`. +### Alternate functions + +All pins are configured as GPIO by default, so normally pinctrl configuration +for GPIO pins is not required. Note that on NPCX ECs some pins default to a +non-GPIO function after reset. These are explicitly set to GPIO during +initialization, based on the `def-io-conf-list` node in [npcx9.dtsi], so they +do not need to be set to GPIO usage, but they need an explicit `pinctrl-x` +entry to be set back to the specific function. + ### Legacy enum-name usage Only GPIOs that require referencing from legacy common code should have @@ -241,18 +250,18 @@ For example on the Volteer reference board: Low voltage pins configuration depends on the specific chip family. -For Nuvoton, this is done using a [nuvoton,npcx-lvolctrl-def] devicetree node, -with a `lvol-io-pads` property listing all the pins that have to be configured -for low-voltage operation. For example: +For Nuvoton, this is done using the `GPIO_VOLTAGE_1P8` flag in the `named-gpios` +child node. For example ``` -def-lvol-io-list { - compatible = "nuvoton,npcx-lvolctrl-def"; - lvol-io-pads = < - &lvol_iob3 /* EC_I2C_SENSOR_SCL */ - &lvol_iob2 /* EC_I2C_SENSOR_SDA */ - >; -}; +named-gpios { + compatible = "named-gpios"; + ... + ec-i2c-sensor-scl { + gpios = <&gpiob 5 (GPIO_INPUT | GPIO_VOLTAGE_1P8)>; + }; + ... +} ``` For ITE, this is done using the `GPIO_VOLTAGE_1P8` flag in the `named-gpios` @@ -456,4 +465,5 @@ project. [gpio.dts]: ../../zephyr/projects/volteer/volteer/gpio.dts [interrupts.dts]: ../../zephyr/projects/volteer/volteer/interrupts.dts [BUILD.py]: ../../zephyr/projects/volteer/volteer/BUILD.py -[*node label*]: https://docs.zephyrproject.org/latest/build/dts/intro.html#dt-node-labels
\ No newline at end of file +[*node label*]: https://docs.zephyrproject.org/latest/build/dts/intro.html#dt-node-labels +[npcx9.dtsi]: https://github.com/zephyrproject-rtos/zephyr/blob/main/dts/arm/nuvoton/npcx9.dtsi diff --git a/docs/zephyr/zephyr_i2c.md b/docs/zephyr/zephyr_i2c.md index da54a373a5..f8d17381d7 100644 --- a/docs/zephyr/zephyr_i2c.md +++ b/docs/zephyr/zephyr_i2c.md @@ -101,7 +101,7 @@ named-i2c-ports { battery { i2c-port = <&i2c0_0>; remote-port = <0>; - enum-name = "I2C_PORT_BATTERY"; + enum-names = "I2C_PORT_BATTERY"; } }; ``` @@ -115,13 +115,9 @@ named-i2c-ports { battery { i2c-port = <&i2c0_0>; remote-port = <0>; - enum-name = "I2C_PORT_BATTERY"; + enum-names = "I2C_PORT_BATTERY", + "I2C_PORT_CHARGER"; } - charger { - i2c-port = <&i2c0_0>; - remote-port = <0>; - enum-name = "I2C_PORT_CHARGER"; - }; }; ``` @@ -307,39 +303,30 @@ below: i2c_sensor: sensor { i2c-port = <&i2c0_0>; - enum-name = "I2C_PORT_SENSOR"; - }; - i2c-accel { - i2c-port = <&i2c0_0>; - enum-name = "I2C_PORT_ACCEL"; + enum-names = "I2C_PORT_SENSOR", + "I2C_PORT_ACCEL"; }; i2c_usb_c0: usb-c0 { i2c-port = <&i2c1_0>; - enum-name = "I2C_PORT_USB_C0"; + enum-names = "I2C_PORT_USB_C0"; }; i2c_usb_c1: usb-c1 { i2c-port = <&i2c2_0>; - enum-name = "I2C_PORT_USB_C1"; + enum-names = "I2C_PORT_USB_C1"; }; usb1-mix { i2c-port = <&i2c3_0>; - enum-name = "I2C_PORT_USB_1_MIX"; + enum-names = "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"; + enum-names = "I2C_PORT_POWER", + "I2C_PORT_BATTERY"; }; eeprom { i2c-port = <&i2c7_0>; - enum-name = "I2C_PORT_EEPROM"; - }; - charger { - i2c-port = <&i2c7_0>; - enum-name = "I2C_PORT_CHARGER"; + enum-names = "I2C_PORT_EEPROM", + "I2C_PORT_CHARGER"; }; }; ``` diff --git a/docs/zephyr/zephyr_leds.md b/docs/zephyr/zephyr_leds.md new file mode 100644 index 0000000000..b29b4ab610 --- /dev/null +++ b/docs/zephyr/zephyr_leds.md @@ -0,0 +1,223 @@ +# Zephyr EC LEDs + +[TOC] + +## Overview + +[LEDs](../ec_terms.md#led) provide status about the following: + +- Dedicated battery state/charging state +- Chromebook power +- Adapter power +- Left side USB-C port (battery state/charging state) +- Right side USB-C port (battery state/charging state) +- Recovery mode +- Debug mode + +LEDs can be configured as simple GPIOs, with on/off control only, or as [PWM](../ec_terms.md#pwm) with +adjustment brightness and color. + +## Kconfig Options + +The `CONFIG_PLATFORM_EC_LED_DT` option, found in the [Kconfig.led_dt](../../zephyr/Kconfig.led_dt) file, enables devicetree based configuration of LED +policies and colors. + +Enabling the devicetree LED implementation requires that you disable the legacy EC implementation. + +Example: +``` +# LED +CONFIG_PLATFORM_EC_LED_COMMON=n +CONFIG_PLATFORM_EC_LED_DT=y +``` + +Enable other [config options](../configuration/leds.md) supported in the legacy code. + +## Devicetree Nodes + +LEDs are configured in two steps. + +### Configure LED colors +The LED colors are configured using either GPIO based LEDs or PWM based LEDs. + +#### GPIO based LEDs +Configure GPIO based LEDs using `cros-ec,gpio-led-pins` compatible node described by [cros-ec,gpio_led_pins.yaml]. + +Example: + +For this example, the board contains dual-channel LED, one channel turns on the blue color, and one channel turns on the amber color. +To set the LED color to amber, the yellow channel is enabled and the blue channel is disabled. + +``` +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 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 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 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 0>, + <&gpio_ec_chg_led_b_c1 0>; + }; +}; +``` +GPIO LED Pins dts file example: [led_pins_herobrine.dts] + +#### PWM based LEDs +Configure PWM based LEDs with two separate nodes. +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. + +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. +``` +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>; + }; +}; + +pwm-led-pins { + compatible = "cros-ec,pwm-led-pins"; + pwm-frequency = <100>; + /* Amber - turn on yellow LED */ + color_amber: color-amber { + led-pins = <&pwm_y 100>, + <&pwm_w 0>; + }; + /* White - turn on white LED */ + color_white: color-white { + led-pins = <&pwm_y 0>, + <&pwm_w 100>; + }; + /* Off - turn off both LEDs */ + color_off: color-off { + led-pins = <&pwm_y 0>, + <&pwm_w 0>; + }; +}; +``` + +PWM LED Pins dts file example: [led_pins_skyrim.dts] + +### Configure LED Policies +`cros-ec,led-policy` nodes describe the LED policy and set the LED behavior by referencing `cros-ec,gpio-led-pins` or `cros-ec,pwm-led-pins` nodes. +These are described in [cros-ec,led_policy.yaml] + + +Example: + +Color policies to configure physical behavior of an LED + +e.g. If you want an LED to blink, create 2 color policies, one to turn on the LED and one to turn off the LED. + +``` +color-0 { + led-color = <&color_amber>; + period-ms = <1000>; + }; +color-1 { + led-color = <&color-off>; + period-ms = <1000>; + }; +``` + +To tie this behavior with a system state, properties defining system state and color policies are added to `cros-ec,led-policy` node. + +e.g. To add a blinking behavior for a system state where charge-state is "PWR_STATE_DISCHARGE and chipset-state is "POWER_S3", a policy node +is defined as below. + +``` +led-policy { + compatible = "cros-ec,led-policy"; + ... + ... + power-state-discharge-s3 { + charge-state = "PWR_STATE_DISCHARGE"; + chipset-state = "POWER_S3"; + + /* Amber 1 sec, off 3 sec */ + color-0 { + led-color = <&color_amber>; + period-ms = <1000>; + }; + color-1 { + led-color = <&color_off>; + period-ms = <3000>; + }; + }; + ... + ... +} +``` + +Note: It is recommended to split the policy specification and the pins specification into two devicetree files. e.g. [led_policy_skyrim.dts], [led_pins_skyrim.dts] + +LED policy dts file examples +[led_policy_skyrim.dts], [led_policy_herobrine.dts] + +## Board Specific Code + +None + +## Threads + +The LEDs are controlled by hook task in the file [led_driver/led.c](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/shim/src/led_driver/led.c). + +## Testing and Debugging +TODO: Enable support for ledtest + +## Examples + +### How to setup LEDs and add nodes + + + +- 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 [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]. + +### PWM + +[Example CL enabling single port pwm based LEDs] + +### GPIO + +[Example CL enabling dual port gpio based LEDs] + +<!-- Reference Links --> +[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 +[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_new_board_checklist.md b/docs/zephyr/zephyr_new_board_checklist.md index eb4584af2c..9baaaf4c42 100644 --- a/docs/zephyr/zephyr_new_board_checklist.md +++ b/docs/zephyr/zephyr_new_board_checklist.md @@ -64,7 +64,7 @@ EC Feature | Ne [Configure Batteries](./zephyr_battery.md) | no [Configure CrOS Board Information (CBI)](./zephyr_cbi.md) | no [Configure Keyboard (TODO)](./zephyr_template.md) | no -[Configure LEDs (TODO)](./zephyr_template.md) | no +[Configure LEDs](./zephyr_leds.md) | no [Configure Motion Sensors](./zephyr_motionsense.md) | no [Configure BC1.2 Charger Detector (TODO)](./zephyr_template.md) | no [Configure ADC](./zephyr_adc.md) | no diff --git a/docs/zephyr/zephyr_temperature_sensor.md b/docs/zephyr/zephyr_temperature_sensor.md index 15e93e1e4e..8ee87a84f7 100644 --- a/docs/zephyr/zephyr_temperature_sensor.md +++ b/docs/zephyr/zephyr_temperature_sensor.md @@ -74,22 +74,26 @@ on Zephyr-based boards. ## Device Tree Nodes -Temperature sensors are declared in a `named-temp-sensors section` in the device -tree. This example is from [zephyr/boards/arm/brya/brya.dts](../../zephyr/boards/arm/brya/brya.dts): +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/projects/brya/temp_sensors.dts](../../zephyr/projects/brya/temp_sensors.dts): ``` + temp_ddr_soc: ddr_soc { + compatible = "cros-ec,temp-sensor-thermistor"; + thermistor = <&thermistor_3V3_30K9_47K_4050B>; + adc = <&adc_ddr_soc>; + }; + named-temp-sensors { + compatible = "cros-ec,temp-sensors"; ddr_soc { - compatible = "cros-ec,temp-sensor"; - thermistor = <&thermistor_3V3_30K9_47K_4050B>; - label = "DDR and SOC"; - enum-name = "TEMP_SENSOR_1_DDR_SOC"; temp_fan_off = <35>; temp_fan_max = <60>; temp_host_high = <85>; temp_host_halt = <90>; temp_host_release_high = <80>; - adc = <&adc_ddr_soc>; + sensor = <&temp_ddr_soc>; }; ``` diff --git a/docs/zephyr/zephyr_testing.md b/docs/zephyr/zephyr_testing.md new file mode 100644 index 0000000000..5f5987686c --- /dev/null +++ b/docs/zephyr/zephyr_testing.md @@ -0,0 +1,53 @@ +# Zephyr Testing Resources + +This is a compilation of resources for developers participating in the Zephyr +EC Fix-it Week, running from 15 - 19 Aug 2022. + +Please note: many of the links in this document will only be accessible to +Googlers. + +[TOC] + +## Introductory materials + + * [Fix-it week Training Presentation](https://goto.google.com/cros-ec-fixit-week-presentation) - + by Yuval Peress (Start here - Googlers only) + * Ask questions during the live presentation using the + [Dory](https://goto.google.com/cros-ec-fixit-week-dory) (Google only) + * Sample CLs for your reference: + * [Writing a new emulator](https://crrev.com/c/2903206) + * [Writing a console command test ](https://crrev.com/c/3594484) + * [Writing a host command test](https://crrev.com/c/3530114) + * [Using test fixtures and local FFF mocks](https://crrev.com/c/3607055) + * [Defining global FFF mocks](https://crrev.com/c/3252365) + * [Resetting global FFF mocks](https://crrev.com/c/3500299) + +## Finding Work to do + +We have assembled a [hotlist](http://b/hotlists/4300616) of low-coverage areas +in the codebase. Please remember to assign bugs to yourself to avoid duplicate +work being performed and do not take bugs until you are ready to actively work +on it. + +We also encourage you to check our coverage reports to identify files needing +additional test coverage: + + * [Gitlab coverage reports](https://gitlab.com/zephyr-ec/ec/-/jobs/artifacts/main/file/build/all_builds_filtered_rpt/index.html?job=merged_coverage) + * [Internal Code Search](https://goto.google.com/cros-ec-fixit-week-cs) + (enable the coverage layer - Googlers only) + +## Submitting tests for review + +The fastest way to have your code reviewed is to add +`zephyr-test-eng@google.com` to your CL. This will randomly assign a +member of the Zephyr EC Testing team to your CL. The team will be monitoring +Gerrit extra closely during Fix-it week to streamline reviews. Please do _not_ +send CLs directly to individuals or to the wider Zephyr reviewers group. + +## Getting Help + +Questions on writing, running, and debugging tests should be asked in [YAQS with +the zephyr-rtos-test topic](https://goto.google.com/cros-ec-fixit-week-yaqs). +Part of our goal during Fix-it Week is to assemble a knowledge base of testing +information. Your questions and the resulting dialogue will be very beneficial +to future developers, so please ask away! (Googlers only) diff --git a/docs/zephyr/zephyr_troubleshooting.md b/docs/zephyr/zephyr_troubleshooting.md new file mode 100644 index 0000000000..646240ce18 --- /dev/null +++ b/docs/zephyr/zephyr_troubleshooting.md @@ -0,0 +1,184 @@ +# Zephyr Troubleshooting + +[TOC] + +## Devicetree + +The devicetree is made out of different dts and dtsi files, gets aggregated +into a single `zephyr.dts` file and generates a `devicetree_generated.h` header +with all the definitions used by the `DT_` macros. + +The build system lists the various overlay files specified by `BUILD.py`, for +example: + +``` +-- 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 +... +``` + +Useful artifacts (always present): + +Aggregated devicetree file, after all the overlays, preprocessor and +`gen_defines.py`: + +``` +build/zephyr/$PROJECT/build-ro/zephyr/zephyr.dts +``` + +Main devicetree output, flat representation of the tree and various node +references, including ordinals of `dts_ord_...` structs: + +``` +./build/zephyr/$PROJECT/build-ro/zephyr/include/generated/devicetree_generated.h +``` + +For more details see: [CMake configuration phase](https://docs.zephyrproject.org/latest/build/cmake/index.html?highlight=gen_defines%20py#configuration-phase) + +## Node nomenclature + +``` +/ { + a-node { + subnode_nodelabel: a-sub-node { + foo = <3>; + label = "SUBNODE"; + }; + }; +}; +``` + +- `/` is the root node +- `a-node` and `a-sub-node` are node names +- `subnode_nodelabel` is a nodelabel +- `foo` is a property, `3` is the value +- `label` is a property, `SUBNODE` is the value + +NOTE: `subnode_nodelabel` is a nodelabel, `label` is a label property. + +## Adding multiple nodelabels + +Code can have hardcoded nodelables, so sometimes it's useful to add extra +nodelabels to an existing node (referenced by another nodelabel). To do that +add an overlay with something similar to: + +``` +another_node_label: &subnode_nodelabel { +}; +``` + +## Undefined reference to \_\_device\_dts\_ord\_... + +This happens when some code refer to a device using `DT_DEVICE_GET`, but the +corresponding `struct device` is not instantiated, either because the driver +has not been enabled or because of a devicetree misconfiguration (missing +`status = "okay"`). + +Quick fix: enable the corresponding driver (CONFIG_...=y) or fix the devicetree. + +Proper fix: find the code referencing to the undefined node, make sure that the +corresponding Kconfig option depends on the subsystem being enabled (ADC, +I2C...), make sure that the specific platform driver is enabled based on the +devicetree (`default y` and `depends on DT_HAS_...`). + +## error: 'CONFIG_..._LOG_LEVEL' undeclared + +The `CONFIG_..._LOG_LEVEL` symbols are not defined directly (i.e. there's no +Kconfig `config ..._LOG_LEVEL`), they are generated using the +`subsys/logging/Kconfig.template.log_config` template. + +Quick fix: enable the logging subsystem (normally `CONFIG_LOG=y` +`CONFIG_LOG_MODE_MINIMAL=y` in the project `prj.conf`), or change the code so +that the driver builds without this config. + +Fix: make the driver depends on the logging subsystem being enabled (`depends +on LOG`) or change the code to compile with `CONFIG_LOG=n`. + +## Menuconfig + +Sometimes it's useful to run the `menuconfig` target on a specific project, +this can be done with: + +``` +ninja -C build/zephyr/$PROJECT/build-ro menuconfig +``` + +This exposes all the available options from the various Kconfig fragments and +can be useful to validate that config constraints are working correctly. + +For example, searching for `^SSHELL$` (using the `/` key) shows: + +``` +Name: SHELL +Prompt: Shell +Type: bool +Value: y + +Symbols currently n-selecting this symbol (no effect): +... + +Symbols currently y-implying this symbol: + - CROS_EC + - PLATFORM_EC +``` + +## LTO + +Many compiler and linker error are very uninformative if LTO is enabled, for +example a missing `struct device` can show as + +``` +/tmp/ccCiGy7c.ltrans0.ltrans.o:(.rodata+0x6a0): undefined reference to `__device_dts_ord_75' +``` + +Adding `CONFIG_LTO=n` to the corresponding `prj.conf` usually results in more +useful error messages, for example: + +``` +modules/ec/libec_shim.a(adc.c.obj):(.rodata.adc_channels+0x58): undefined reference to `__device_dts_ord_75' +``` + +## Build artifacts + +The buildsystem can be configured to leave the build artifact next to the +object files, this is useful to inspect the macro output. To do that use the +`zmake` flag: + +``` +zmake build $PROJECT --extra-cflags=-save-temps=obj +``` + +This leaves a bunch of `.i` files in the build/ directory. + +For more information see: [Look at the preprocessor output](https://docs.zephyrproject.org/latest/build/dts/troubleshooting.html?highlight=save%20temps#look-at-the-preprocessor-output). + +This is also useful to analyze assembly errors, for example + +``` +/tmp/cctFuB4N.s: Assembler messages: +/tmp/cctFuB4N.s:1869: Error: missing expression +``` + +becomes + +``` +zephyr/CMakeFiles/zephyr.dir/misc/generated/configs.c.s: Assembler messages: +zephyr/CMakeFiles/zephyr.dir/misc/generated/configs.c.s:1869: Error: missing expression +``` + +## Statically initialized objects + +The `zephyr.elf` output file can be used with gdb to analyze all the statically +allocated structures, for example: + +``` +$ arm-none-eabi-gdb build/zephyr/$PROJECT/output/zephyr-ro.elf +(gdb) p fan_config +$1 = {{pwm = {dev = 0x100ad244 <__device_dts_ord_169>, channel = 0, period = 1000000, flags = 0}, tach = 0x100ad43c <__device_dts_ord_172>}} +(gdb) p __device_dts_ord_172.name +$3 = 0x100ba480 "tach@400e1000" +``` + +If the symbol has been optimized, try rebuilding with `CONFIG_LTO=n`. diff --git a/docs/zephyr/ztest.md b/docs/zephyr/ztest.md index 6bb121045d..d782631cc3 100644 --- a/docs/zephyr/ztest.md +++ b/docs/zephyr/ztest.md @@ -142,7 +142,6 @@ find-and-replace. * `TEST_BITS_CLEARED(a, bits)` to `zassert_true(a & (int)bits == 0, "%u, 0", a & (int)bits)` * `TEST_ASSERT_ARRAY_EQ(s, d, n)` to `zassert_mem_equal(s, d, b, NULL)` -* `TEST_CHECK(n)` to `zassert_true(n, NULL)` * `TEST_NEAR(a, b, epsilon, fmt)` to `zassert_within(a, b, epsilon, fmt, a)` * Currently, every usage of `TEST_NEAR` involves floating point values * `TEST_ASSERT_ABS_LESS(n, t)` to `zassert_true(abs(n) < t, "%d, %d", n, t)` |
