Re: [PATCH] dt-bindings: backlight: Convert common backlight bindings to DT schema

On Fri, Jun 19, 2020 at 3:53 PM Sam Ravnborg sam@ravnborg.org wrote:

Hi Rob.

Good to have these converted. A few comments in the following. One comment is for the backlight people as you copied the original text.

    Sam

On Thu, Jun 18, 2020 at 04:44:13PM -0600, Rob Herring wrote:

...

Convert the common GPIO, LED, and PWM backlight bindings to DT schema format.

Given there's only 2 common properties and the descriptions are slightly different, I opted to not create a common backlight schema.

Cc: Lee Jones lee.jones@linaro.org Cc: Daniel Thompson daniel.thompson@linaro.org Cc: Jingoo Han jingoohan1@gmail.com Signed-off-by: Rob Herring robh@kernel.org

---

.../leds/backlight/gpio-backlight.txt | 16 --- .../leds/backlight/gpio-backlight.yaml | 41 ++++++++ .../bindings/leds/backlight/led-backlight.txt | 28 ------ .../leds/backlight/led-backlight.yaml | 58 +++++++++++ .../bindings/leds/backlight/pwm-backlight.txt | 61 ------------ .../leds/backlight/pwm-backlight.yaml | 98 +++++++++++++++++++ 6 files changed, 197 insertions(+), 105 deletions(-) delete mode 100644 Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt create mode 100644 Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml delete mode 100644 Documentation/devicetree/bindings/leds/backlight/led-backlight.txt create mode 100644 Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml delete mode 100644 Documentation/devicetree/bindings/leds/backlight/pwm-backlight.txt create mode 100644 Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml

diff --git a/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt deleted file mode 100644 index 321be6640533..000000000000 --- a/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt +++ /dev/null @@ -1,16 +0,0 @@ -gpio-backlight bindings

-Required properties:

• • compatible: "gpio-backlight"
• • gpios: describes the gpio that is used for enabling/disabling the backlight.
• refer to bindings/gpio/gpio.txt for more details.

-Optional properties:

• • default-on: enable the backlight at boot.

-Example:

• backlight {
  

•         compatible = "gpio-backlight";
  

•         gpios = <&gpio3 4 GPIO_ACTIVE_HIGH>;
  

•         default-on;
  

• };
  

diff --git a/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml new file mode 100644 index 000000000000..75cc569b9c55 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/backlight/gpio-backlight.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml#

+title: gpio-backlight bindings

+maintainers:

• • Lee Jones lee.jones@linaro.org
• • Daniel Thompson daniel.thompson@linaro.org
• • Jingoo Han jingoohan1@gmail.com

+properties:

• compatible:
• const: gpio-backlight
• gpios:
• description: The gpio that is used for enabling/disabling the backlight.
• maxItems: 1
• default-on:
• description: enable the backlight at boot.
• type: boolean

+required:

• • compatible
• • gpios

+additionalProperties: false

+examples:

• • |
• #include <dt-bindings/gpio/gpio.h>
• backlight {

•    compatible = "gpio-backlight";
  

•    gpios = <&gpio3 4 GPIO_ACTIVE_HIGH>;
  

•    default-on;
  

• };

+... diff --git a/Documentation/devicetree/bindings/leds/backlight/led-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/led-backlight.txt deleted file mode 100644 index 4c7dfbe7f67a..000000000000 --- a/Documentation/devicetree/bindings/leds/backlight/led-backlight.txt +++ /dev/null @@ -1,28 +0,0 @@ -led-backlight bindings

-This binding is used to describe a basic backlight device made of LEDs. -It can also be used to describe a backlight device controlled by the output of -a LED driver.

-Required properties:

• • compatible: "led-backlight"
• • leds: a list of LEDs

-Optional properties:

• • brightness-levels: Array of distinct brightness levels. The levels must be

•                   in the range accepted by the underlying LED devices.
  

•                   This is used to translate a backlight brightness level
  

•                   into a LED brightness level. If it is not provided, the
  

•                   identity mapping is used.
  

• • default-brightness-level: The default brightness level.

-Example:

• backlight {
  

•         compatible = "led-backlight";
  

•         leds = <&led1>, <&led2>;
  

•         brightness-levels = <0 4 8 16 32 64 128 255>;
  

•         default-brightness-level = <6>;
  

• };
  

diff --git a/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml new file mode 100644 index 000000000000..ae50945d2798 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/backlight/led-backlight.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml#

+title: led-backlight bindings

+maintainers:

• • Lee Jones lee.jones@linaro.org
• • Daniel Thompson daniel.thompson@linaro.org
• • Jingoo Han jingoohan1@gmail.com

+description:

• This binding is used to describe a basic backlight device made of LEDs. It
• can also be used to describe a backlight device controlled by the output of
• a LED driver.

+properties:

• compatible:
• const: led-backlight
• leds:
• description: A list of LED nodes
• $ref: /schemas/types.yaml#/definitions/phandle-array
• brightness-levels:
• description: Array of distinct brightness levels. The levels must be

•  in the range accepted by the underlying LED devices. This is used
  

•  to translate a backlight brightness level into a LED brightness level.
  

•  If it is not provided, the identity mapping is used.
  

• $ref: /schemas/types.yaml#/definitions/uint32-array

bike-shedding. To me it is a tad easier to read when multi-line descriptions are on a separate line. So "description:" on one line, and the text on following lines. example-schema.yaml does both - so both are official acceptable.

I agree, but the one issue is ruamel yaml wants it the above way unless you do '|' (or really '>' may be the correct annotation here). That's mainly an issue if doing tree wide yaml->python processing->yaml transformations. But if the line lengths don't match exactly what ruamel is set to, then it reformats it anyways, so in the end it doesn't really matter. I just have to filter out unwanted reformatting (until ruamel can really do roundtrips with no reformatting).

Rob