summaryrefslogtreecommitdiff
path: root/docs/zephyr
diff options
context:
space:
mode:
Diffstat (limited to 'docs/zephyr')
-rw-r--r--docs/zephyr/README.md5
-rw-r--r--docs/zephyr/project_config.md4
-rw-r--r--docs/zephyr/zephyr_adc.md36
-rw-r--r--docs/zephyr/zephyr_battery.md2
-rw-r--r--docs/zephyr/zephyr_bc12.md45
-rw-r--r--docs/zephyr/zephyr_build.md2
-rw-r--r--docs/zephyr/zephyr_charger.md2
-rw-r--r--docs/zephyr/zephyr_eeprom.md1
-rw-r--r--docs/zephyr/zephyr_gpio.md32
-rw-r--r--docs/zephyr/zephyr_i2c.md37
-rw-r--r--docs/zephyr/zephyr_leds.md223
-rw-r--r--docs/zephyr/zephyr_new_board_checklist.md2
-rw-r--r--docs/zephyr/zephyr_temperature_sensor.md18
-rw-r--r--docs/zephyr/zephyr_testing.md53
-rw-r--r--docs/zephyr/zephyr_troubleshooting.md184
-rw-r--r--docs/zephyr/ztest.md1
16 files changed, 544 insertions, 103 deletions
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
+
+![Alt text](https://screenshot.googleplex.com/4eqXmo2jLcSD6eL.png)
+
+- 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)`
View Lorry Controller Status