zephyr: LED: yaml files cleanup

Rename cros-ec,led-colors.yaml to cros-ec,led-policy.yaml to avoid name
conflict with child node of the same name and to reflect the purpose of
the nodes. Also, update description of properties.

BRANCH=None
BUG=b:227798487
TEST=zmake build --all

Signed-off-by: Parth Malkan <parthmalkan@google.com>
Cq-Depend: chromium:3685751, chromium:3685752
Cq-Depend: chromium:3685753, chromium:3783354
Cq-Depend: chromium:3783355, chromium:3783356
Cq-Depend: chromium:3783357, chromium:3783185
Cq-Depend: chromium:3783183
Change-Id: I10567f48da3978ead99150bf23853d3a376a14ba
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3685750
Tested-by: Bob Moragues <moragues@chromium.org>
Commit-Queue: Bob Moragues <moragues@chromium.org>
Reviewed-by: Keith Short <keithshort@chromium.org>

4 files changed, 161 insertions, 128 deletions

diff --git a/zephyr/dts/bindings/leds/cros-ec,gpio-led-pins.yaml b/zephyr/dts/bindings/leds/cros-ec,gpio-led-pins.yaml
index 53688a8172..59bf450c73 100644
--- a/zephyr/dts/bindings/leds/cros-ec,gpio-led-pins.yaml
+++ b/zephyr/dts/bindings/leds/cros-ec,gpio-led-pins.yaml
@@ -7,20 +7,24 @@ description: GPIO LED pins parent node
 compatible: "cros-ec,gpio-led-pins"
 
 child-binding:
-    description: Each child node describes all the GPIO pins that need to be
-                 altered to set a specific color. Eg. for a board supporting
-                 Blue and Amber LEDs - to set LED_AMBER color, amber LED will
-                 need to be set to 1 and blue LED to 0. So a node looks like
-                 color-amber {
-                              led-color = "LED_AMBER";
-                              led-pins = <&gpio_ec_chg_led_y_c1 1>,
-                                         <&gpio_ec_chg_led_b_c1 0>;
-                             };
+    description: |
+      Each child node describes all the GPIO pins that need to be altered to set
+      a specific color.
+      e.g. For a board supporting Blue and Amber LEDs - to set LED_AMBER color,
+      amber LED will need to be set to 1 and blue LED to 0. 1 always turns on
+      the LED and 0 always turns off the LED. So a node looks like
+      color-amber {
+                   led-color = "LED_AMBER";
+                   led-pins = <&gpio_ec_chg_led_y_c1 1>,
+                              <&gpio_ec_chg_led_b_c1 0>;
+                  };
     properties:
         led-color:
             type: string
             required: true
-            description: Used to link the color nodes with the pin nodes
+            description: |
+              This property is used to identify pin nodes based on color enum.
+              It is required by the EC_CMD_LED_CONTROL host command.
             enum:
                 - LED_OFF
                 - LED_RED
@@ -32,10 +36,9 @@ child-binding:
         led-id:
             type: string
             required: true
-            description: Used to link the color nodes with the pin nodes in
-                         case of multiple LEDs. Also required by ectool to
-                         identify led-ids supported. It needs to match the
-                         enum names defined in ec_commands.h
+            description: |
+              This property is required by the EC_CMD_LED_CONTROL host command.
+              It must match the enum names defined in ec_commands.h.
             enum:
                 - EC_LED_ID_BATTERY_LED
                 - EC_LED_ID_POWER_LED
@@ -47,8 +50,9 @@ child-binding:
         br-color:
             type: string
             required: false
-            description: This is used in the ectool brightness range APIs.
-                         It needs to match the enum names defined in ec_commands.h
+            description: |
+              This is used in the ectool brightness range APIs. It must match
+              the enum names defined in ec_commands.h.
             enum:
                 - EC_LED_COLOR_RED
                 - EC_LED_COLOR_GREEN
@@ -58,4 +62,9 @@ child-binding:
                 - EC_LED_COLOR_AMBER
         led-pins:
             type: phandle-array
-            required: false
+            required: true
+            description: |
+              This property is used to specify an array of gpio pins and
+              corresponding values to enable a particular color.
+              e.g. Amber color - led-pins = <&gpio_ec_chg_led_y_c1 1>,
+                                            <&gpio_ec_chg_led_b_c1 0>;
diff --git a/zephyr/dts/bindings/leds/cros-ec,led-colors.yaml b/zephyr/dts/bindings/leds/cros-ec,led-colors.yaml
deleted file mode 100644
index cd10ca9a60..0000000000
--- a/zephyr/dts/bindings/leds/cros-ec,led-colors.yaml
+++ /dev/null
@@ -1,94 +0,0 @@
-# Copyright 2021 The Chromium OS Authors. All rights reserved.
-# Use of this source code is governed by a BSD-style license that can be
-# found in the LICENSE file.
-
-description: LED colors parent node
-
-compatible: "cros-ec,led-colors"
-
-child-binding:
-    description: LED Color nodes to describe the policy combination a node
-                 depends on, and the color to set to for that combination.
-                 e.g. If Blue color needs to be set for charge state discharge
-                 in S0, a node looks like
-                 power-state-discharge-s0 {
-                    charge-state = "PWR_STATE_DISCHARGE";
-                    chipset-state = "POWER_S0";
-                    color-0 {
-                      led-color = "LED_BLUE";
-                    };
-                 };
-
-    properties:
-        charge-state:
-            description: If the LED color depends on charge state, this
-                         property is used to describe it.
-            type: string
-            required: false
-            enum:
-                - PWR_STATE_CHARGE
-                - PWR_STATE_DISCHARGE
-                - PWR_STATE_ERROR
-                - PWR_STATE_IDLE
-                - PWR_STATE_CHARGE_NEAR_FULL
-
-        charge-port:
-            description: If the LED color depends on the charging port (left or right)
-            type: int
-            required: false
-
-        chipset-state:
-            description: If the LED color depends on chipset state, this
-                         property is used to describe it.
-            type: string
-            required: false
-            enum:
-                - POWER_S0
-                - POWER_S3
-                - POWER_S5
-
-        batt-lvl:
-            description: If the LED color depends on current battery level, this property
-                         is used to describe the batt_lvl range using closed interval [x,y].
-                         Use the macros defined in dt-bindings/battery.h.
-                         e.g. <BATTERY_LEVEL_EMPTY BATTERY_LEVEL_LOW> describes battery level
-                         range of BATTERY_LEVEL_EMPTY to BATTERY_LEVEL_LOW inclusive.
-            type: array
-            required: false
-
-        extra-flag:
-            description: If the LED color depends on additional factors
-            type: string
-            required: false
-            enum:
-                - NONE
-                - LED_CHFLAG_FORCE_IDLE
-                - LED_CHFLAG_DEFAULT
-
-    child-binding:
-        description: Color enum
-        properties:
-            led-color:
-                description: Handle to LED pins node that describes pins to set
-                             to enable a particular color
-                type: phandle
-                required: true
-            period-ms:
-                description: In case of blinking LEDs, amount of time in msecs
-                             the LED color is active. This value must be a
-                             multiple of HOOK_TICK_INTERVAL_MS
-                             e.g.
-                             power-state-error {
-                                charge-state = "PWR_STATE_ERROR";
-                                /* One sec Amber, one sec Off */
-                                color-0 {
-                                  led-color = "LED_AMBER";
-                                  period-ms = <1000>;
-                                };
-                                color-1 {
-                                  led-color = "LED_OFF";
-                                  period-ms = <1000>;
-                                };
-                             };
-                type: int
-                required: false
diff --git a/zephyr/dts/bindings/leds/cros-ec,led-policy.yaml b/zephyr/dts/bindings/leds/cros-ec,led-policy.yaml
new file mode 100644
index 0000000000..206ccdb143
--- /dev/null
+++ b/zephyr/dts/bindings/leds/cros-ec,led-policy.yaml
@@ -0,0 +1,110 @@
+# Copyright 2021 The Chromium OS Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+
+description: LED policy parent node
+
+compatible: "cros-ec,led-policy"
+
+child-binding:
+    description: |
+      LED policy nodes to describe the policy combination a node depends on, and
+      the color to set to for that combination.
+      e.g. If Blue color needs to be set for charge state discharge in S0, a
+      node looks like
+      power-state-discharge-s0 {
+         charge-state = "PWR_STATE_DISCHARGE";
+         chipset-state = "POWER_S0";
+         charge-port = <0>;
+         color-0 {
+           led-color = <&color_blue>;
+         };
+      };
+
+    properties:
+        charge-state:
+            description: |
+              If the LED color depends on charge state, this property is used
+              to describe it.
+            type: string
+            required: false
+            enum:
+                - PWR_STATE_CHARGE
+                - PWR_STATE_DISCHARGE
+                - PWR_STATE_ERROR
+                - PWR_STATE_IDLE
+                - PWR_STATE_CHARGE_NEAR_FULL
+
+        charge-port:
+            description: |
+              If the LED color depends on the charging port (left or right).
+            type: int
+            required: false
+
+        chipset-state:
+            description: |
+              If the LED color depends on chipset state, this property is used
+              to describe it.
+            type: string
+            required: false
+            enum:
+                - POWER_S0
+                - POWER_S3
+                - POWER_S5
+
+        batt-lvl:
+            description: |
+              If the LED color depends on current battery level, this property
+              is used to describe batt_lvl range using closed interval [x,y].
+              Use the macros defined in dt-bindings/battery.h.
+              e.g. <BATTERY_LEVEL_EMPTY BATTERY_LEVEL_LOW> describes battery level
+                   range of BATTERY_LEVEL_EMPTY to BATTERY_LEVEL_LOW inclusive.
+            type: array
+            required: false
+
+        extra-flag:
+            description: |
+              This property is used if the LED color depends on additional
+              factors.
+              e.g.
+              LED_CHFLAG_FORCE_IDLE - The LED policy is only applied when battery
+              charging is disabled.
+              LED_CHFLAG_DEFAULT - The LED policy is only applied when battery
+              charging is allowed.
+              NONE - extra-flag is ignored and LED policy is always applied.
+            type: string
+            required: false
+            enum:
+                - NONE
+                - LED_CHFLAG_FORCE_IDLE
+                - LED_CHFLAG_DEFAULT
+
+    child-binding:
+        description: Color enum
+        properties:
+            led-color:
+                description: |
+                  Handle to LED pins node that describes pins to set to enable a
+                  particular color.
+                type: phandle
+                required: true
+            period-ms:
+                description: |
+                  In case of blinking LEDs, amount of time in msecs the LED
+                  color is active. This value must be a multiple of
+                  HOOK_TICK_INTERVAL_MS.
+                  e.g.
+                  power-state-error {
+                     charge-state = "PWR_STATE_ERROR";
+                     /* One sec Amber, one sec Off */
+                     color-0 {
+                       led-color = <&color_amber>;
+                       period-ms = <1000>;
+                     };
+                     color-1 {
+                       led-color = <&color_off>;
+                       period-ms = <1000>;
+                     };
+                  };
+                type: int
+                required: false
diff --git a/zephyr/dts/bindings/leds/cros-ec,pwm-led-pins.yaml b/zephyr/dts/bindings/leds/cros-ec,pwm-led-pins.yaml
index 57f32b0046..0f6b7ae7c9 100644
--- a/zephyr/dts/bindings/leds/cros-ec,pwm-led-pins.yaml
+++ b/zephyr/dts/bindings/leds/cros-ec,pwm-led-pins.yaml
@@ -7,20 +7,23 @@ description: PWM LED pins parent node
 compatible: "cros-ec,pwm-led-pins"
 
 child-binding:
-    description: Each child node describes all the PWM pins that need to be
-                 altered to set a specific color. Eg. For blue and amber PWM
-                 channels, in order to set color amber, a node looks like
-                 this where 100 is PWM duty cycle in percentage
-                 color-amber {
-                              led-color = "LED_AMBER";
-                              led-pins = <&pwm_led_y 100>,
-                                         <&pwm_led_b 0>;
-                             };
+    description: |
+      Each child node describes all the PWM pins that need to be altered to set
+      a specific color.
+      e.g. For blue and amber PWM channels, in order to set color amber, a node
+      looks like this where 100 is PWM duty cycle in percentage.
+      color-amber {
+                   led-color = "LED_AMBER";
+                   led-pins = <&pwm_led_y 100>,
+                              <&pwm_led_b 0>;
+                  };
     properties:
         led-color:
             type: string
             required: true
-            description: Used to link the color nodes with the pin nodes
+            description: |
+              This property is used to identify pin nodes based on color enum.
+              It is required by the EC_CMD_LED_CONTROL host command.
             enum:
                 - LED_OFF
                 - LED_RED
@@ -32,10 +35,9 @@ child-binding:
         led-id:
             type: string
             required: true
-            description: Used to link the color nodes with the pin nodes in
-                         case of multiple LEDs. Also required by ectool to
-                         identify led-ids supported. It needs to match the
-                         enum names defined in ec_commands.h
+            description: |
+              This property is required by the EC_CMD_LED_CONTROL host command.
+              It must match the enum names defined in ec_commands.h.
             enum:
                 - EC_LED_ID_BATTERY_LED
                 - EC_LED_ID_POWER_LED
@@ -47,8 +49,9 @@ child-binding:
         br-color:
             type: string
             required: false
-            description: This is used in the ectool brightness range APIs.
-                         It needs to match the enum names defined in ec_commands.h
+            description: |
+              This is used in the ectool brightness range APIs. It must match
+              the enum names defined in ec_commands.h.
             enum:
                 - EC_LED_COLOR_RED
                 - EC_LED_COLOR_GREEN
@@ -58,4 +61,9 @@ child-binding:
                 - EC_LED_COLOR_AMBER
         led-pins:
             type: phandle-array
-            required: false
+            required: true
+            description: |
+              This property is used to specify an array of PWM pins and
+              corresponding values to enable a particular color.
+              e.g. Amber color - led-pins = <&pwm_led_y 100>,
+                                            <&pwm_led_b 0>;