From b35af7da54d5fce3f7c2ae555e07a895501ed18c Mon Sep 17 00:00:00 2001 From: Parth Malkan Date: Mon, 30 May 2022 12:07:43 -0700 Subject: docs: zephyr: LEDs Add a Zephyr doc for setting up LEDs on a board. BRANCH=none BUG=b:222105941 TEST=Browse in Gerrit TEST=Reviewers Change-Id: If92586ed51593d51f7b786e076db0718fa3e31ff Signed-off-by: Parth Malkan Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3677553 Reviewed-by: Keith Short --- docs/zephyr/zephyr_leds.md | 223 ++++++++++++++++++++++++++++++ docs/zephyr/zephyr_new_board_checklist.md | 2 +- 2 files changed, 224 insertions(+), 1 deletion(-) create mode 100644 docs/zephyr/zephyr_leds.md 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] + + +[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 -- cgit v1.2.1