dt-bindings: backlight: Convert common backlight bindings to DT schema

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 <[email protected]>

Cc Daniel Thompson <[email protected]>

Cc Jingoo Han <[email protected]>

Signed-off-by Rob Herring <[email protected]>

---
 .../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

Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt deleted +0 -16

deleted file mode 100644
index 321be6640533..000000000000
@@ -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;
-	};

Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml new file +41 -0

new file mode 100644
index 000000000000..75cc569b9c55
@@ -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 <[email protected]>
+  - Daniel Thompson <[email protected]>
+  - Jingoo Han <[email protected]>
+
+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;
+    };
+
+...

Documentation/devicetree/bindings/leds/backlight/led-backlight.txt deleted +0 -28

deleted file mode 100644
index 4c7dfbe7f67a..000000000000
@@ -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>;
-	};

Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml new file +22 -0

new file mode 100644
index 000000000000..ae50945d2798
@@ -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 <[email protected]>
+  - Daniel Thompson <[email protected]>
+  - Jingoo Han <[email protected]>
+
+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
+

Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml new file +18 -0

+
+required:
+  - compatible
+  - leds
+
+additionalProperties: false
+
+examples:
+  - |
+    backlight {
+        compatible = "led-backlight";
+
+        leds = <&led1>, <&led2>;
+        brightness-levels = <0 4 8 16 32 64 128 255>;
+        default-brightness-level = <6>;
+    };
+
+...

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.txt deleted +0 -61

deleted file mode 100644
index 64fa2fbd98c9..000000000000
@@ -1,61 +0,0 @@
-pwm-backlight bindings
-
-Required properties:
-  - compatible: "pwm-backlight"
-  - pwms: OF device-tree PWM specification (see PWM binding[0])
-  - power-supply: regulator for supply voltage
-
-Optional properties:
-  - pwm-names: a list of names for the PWM devices specified in the
-               "pwms" property (see PWM binding[0])
-  - enable-gpios: contains a single GPIO specifier for the GPIO which enables
-                  and disables the backlight (see GPIO binding[1])
-  - post-pwm-on-delay-ms: Delay in ms between setting an initial (non-zero) PWM
-                          and enabling the backlight using GPIO.
-  - pwm-off-delay-ms: Delay in ms between disabling the backlight using GPIO
-                      and setting PWM value to 0.
-  - brightness-levels: Array of distinct brightness levels. Typically these
-                       are in the range from 0 to 255, but any range starting at
-                       0 will do. The actual brightness level (PWM duty cycle)
-                       will be interpolated from these values. 0 means a 0% duty
-                       cycle (darkest/off), while the last value in the array
-                       represents a 100% duty cycle (brightest).
-  - default-brightness-level: The default brightness level (index into the
-                              array defined by the "brightness-levels" property).
-  - num-interpolated-steps: Number of interpolated steps between each value
-                            of brightness-levels table. This way a high
-                            resolution pwm duty cycle can be used without
-                            having to list out every possible value in the
-                            brightness-level array.
-
-[0]: Documentation/devicetree/bindings/pwm/pwm.txt
-[1]: Documentation/devicetree/bindings/gpio/gpio.txt
-
-Example:
-
-	backlight {
-		compatible = "pwm-backlight";
-		pwms = <&pwm 0 5000000>;
-
-		brightness-levels = <0 4 8 16 32 64 128 255>;
-		default-brightness-level = <6>;
-
-		power-supply = <&vdd_bl_reg>;
-		enable-gpios = <&gpio 58 0>;
-		post-pwm-on-delay-ms = <10>;
-		pwm-off-delay-ms = <10>;
-	};
-
-Example using num-interpolation-steps:
-
-	backlight {
-		compatible = "pwm-backlight";
-		pwms = <&pwm 0 5000000>;
-
-		brightness-levels = <0 2048 4096 8192 16384 65535>;
-		num-interpolated-steps = <2048>;
-		default-brightness-level = <4096>;
-
-		power-supply = <&vdd_bl_reg>;
-		enable-gpios = <&gpio 58 0>;
-	};

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +40 -0

new file mode 100644
index 000000000000..7e1f109a38a4
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/pwm-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: pwm-backlight bindings
+
+maintainers:
+  - Lee Jones <[email protected]>
+  - Daniel Thompson <[email protected]>
+  - Jingoo Han <[email protected]>
+
+properties:
+  compatible:
+    const: pwm-backlight
+
+  pwms:
+    maxItems: 1
+
+  pwm-names: true
+
+  power-supply:
+    description: regulator for supply voltage
+
+  enable-gpios:
+    description: Contains a single GPIO specifier for the GPIO which enables
+      and disables the backlight
+    maxItems: 1
+
+  post-pwm-on-delay-ms:
+    description: Delay in ms between setting an initial (non-zero) PWM and
+      enabling the backlight using GPIO.
+
+  pwm-off-delay-ms:
+    description: Delay in ms between disabling the backlight using GPIO
+      and setting PWM value to 0.
+
+  brightness-levels:
+    description: Array of distinct brightness levels. Typically these are

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +48 -0

+
+  num-interpolated-steps:
+    description: Number of interpolated steps between each value of brightness-levels
+      table. This way a high resolution pwm duty cycle can be used without
+      having to list out every possible value in the brightness-level array.
+    $ref: /schemas/types.yaml#/definitions/uint32
+
+dependencies:
+  default-brightness-level: [brightness-levels]
+  num-interpolated-steps: [brightness-levels]
+
+required:
+  - compatible
+  - pwms
+  - power-supply
+
+additionalProperties: false
+
+examples:
+  - |
+    backlight {
+        compatible = "pwm-backlight";
+        pwms = <&pwm 0 5000000>;
+
+        brightness-levels = <0 4 8 16 32 64 128 255>;
+        default-brightness-level = <6>;
+
+        power-supply = <&vdd_bl_reg>;
+        enable-gpios = <&gpio 58 0>;
+        post-pwm-on-delay-ms = <10>;
+        pwm-off-delay-ms = <10>;
+    };
+
+  - |
+    // Example using num-interpolation-steps:
+    backlight {
+        compatible = "pwm-backlight";
+        pwms = <&pwm 0 5000000>;
+
+        brightness-levels = <0 2048 4096 8192 16384 65535>;
+        num-interpolated-steps = <2048>;
+        default-brightness-level = <4096>;
+
+        power-supply = <&vdd_bl_reg>;
+        enable-gpios = <&gpio 58 0>;
+    };
+
+...

Signature · 6 lines

2.25.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

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

Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml line 36

Quoted 11 lines

Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml new file +4 -0

new file mode 100644
index 000000000000..ae50945d2798
@@ -0,0 +1,58 @@
...
+
+  default-brightness-level:
+    description: The default brightness level (index into the array defined
+      by the "brightness-levels" property).

This description does not match my understading.
The description says "index into", but in reality this is a value that matches somewhere in the range specified by brightness-levels. So it is not an index.

Maybe I just read it wrong and the description is fine. But when I read index the when it says 6 I would look for brightness-levels[6] equals 128 in the example below.

And this is not how it is coded.

Quoted 49 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +43 -0

new file mode 100644
index 000000000000..7e1f109a38a4
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/pwm-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: pwm-backlight bindings
+
+maintainers:
+  - Lee Jones <[email protected]>
+  - Daniel Thompson <[email protected]>
+  - Jingoo Han <[email protected]>
+
+properties:
+  compatible:
+    const: pwm-backlight
+
+  pwms:
+    maxItems: 1
+
+  pwm-names: true
+
+  power-supply:
+    description: regulator for supply voltage
+
+  enable-gpios:
+    description: Contains a single GPIO specifier for the GPIO which enables
+      and disables the backlight
+    maxItems: 1
+
+  post-pwm-on-delay-ms:
+    description: Delay in ms between setting an initial (non-zero) PWM and
+      enabling the backlight using GPIO.
+
+  pwm-off-delay-ms:
+    description: Delay in ms between disabling the backlight using GPIO
+      and setting PWM value to 0.
+
+  brightness-levels:
+    description: Array of distinct brightness levels. Typically these are
+      in the range from 0 to 255, but any range starting at 0 will do. The
+      actual brightness level (PWM duty cycle) will be interpolated from
+      these values. 0 means a 0% duty cycle (darkest/off), while the last

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml line 50

Quoted 7 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +7 -0

+      value in the array represents a 100% duty cycle (brightest).
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+
+  default-brightness-level:
+    description: The default brightness level (index into the array defined
+      by the "brightness-levels" property).
+    $ref: /schemas/types.yaml#/definitions/uint32

Same comment as before...

Quoted 52 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +48 -0

+
+  num-interpolated-steps:
+    description: Number of interpolated steps between each value of brightness-levels
+      table. This way a high resolution pwm duty cycle can be used without
+      having to list out every possible value in the brightness-level array.
+    $ref: /schemas/types.yaml#/definitions/uint32
+
+dependencies:
+  default-brightness-level: [brightness-levels]
+  num-interpolated-steps: [brightness-levels]
+
+required:
+  - compatible
+  - pwms
+  - power-supply
+
+additionalProperties: false
+
+examples:
+  - |
+    backlight {
+        compatible = "pwm-backlight";
+        pwms = <&pwm 0 5000000>;
+
+        brightness-levels = <0 4 8 16 32 64 128 255>;
+        default-brightness-level = <6>;
+
+        power-supply = <&vdd_bl_reg>;
+        enable-gpios = <&gpio 58 0>;
+        post-pwm-on-delay-ms = <10>;
+        pwm-off-delay-ms = <10>;
+    };
+
+  - |
+    // Example using num-interpolation-steps:
+    backlight {
+        compatible = "pwm-backlight";
+        pwms = <&pwm 0 5000000>;
+
+        brightness-levels = <0 2048 4096 8192 16384 65535>;
+        num-interpolated-steps = <2048>;
+        default-brightness-level = <4096>;
+
+        power-supply = <&vdd_bl_reg>;
+        enable-gpios = <&gpio 58 0>;
+    };
+
+...

Signature · 1 line

2.25.1

Quoted 4 lines

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Quoted 49 lines · Sam Ravnborg

Quoted 49 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +43 -0

new file mode 100644
index 000000000000..7e1f109a38a4
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/pwm-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: pwm-backlight bindings
+
+maintainers:
+  - Lee Jones <[email protected]>
+  - Daniel Thompson <[email protected]>
+  - Jingoo Han <[email protected]>
+
+properties:
+  compatible:
+    const: pwm-backlight
+
+  pwms:
+    maxItems: 1
+
+  pwm-names: true
+
+  power-supply:
+    description: regulator for supply voltage
+
+  enable-gpios:
+    description: Contains a single GPIO specifier for the GPIO which enables
+      and disables the backlight
+    maxItems: 1
+
+  post-pwm-on-delay-ms:
+    description: Delay in ms between setting an initial (non-zero) PWM and
+      enabling the backlight using GPIO.
+
+  pwm-off-delay-ms:
+    description: Delay in ms between disabling the backlight using GPIO
+      and setting PWM value to 0.
+
+  brightness-levels:
+    description: Array of distinct brightness levels. Typically these are
+      in the range from 0 to 255, but any range starting at 0 will do. The
+      actual brightness level (PWM duty cycle) will be interpolated from
+      these values. 0 means a 0% duty cycle (darkest/off), while the last

Quoted 8 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml line 50

Quoted 7 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +7 -0

+      value in the array represents a 100% duty cycle (brightest).
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+
+  default-brightness-level:
+    description: The default brightness level (index into the array defined
+      by the "brightness-levels" property).
+    $ref: /schemas/types.yaml#/definitions/uint32

Same comment as before...

Sorry the "ditto" meant I didn't thing about PWM as much as I should have.

The situation for PWM is a little different to LED. That's mostly because we decided not to clutter the LED code with "num-interpolated-steps".

The PWM code implements the default-brightness-level as an index into the brightness array *after* it has been expanded using interpolation. In other words today Linux treats the default-brightness-level more like[1].

description: The default brightness level. When
num-interpolated-steps is not set this is simply an index into the array defined by the "brightness-levels" property. If num-interpolated-steps is set the brightness array will be expanded by interpolation before we index to get a default level.

This is the best I have come up with so far... but I concede it still lacks elegance.

Quoted 79 lines · Daniel Thompson

Quoted 49 lines · Sam Ravnborg

Quoted 49 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +43 -0

new file mode 100644
index 000000000000..7e1f109a38a4
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/pwm-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: pwm-backlight bindings
+
+maintainers:
+  - Lee Jones <[email protected]>
+  - Daniel Thompson <[email protected]>
+  - Jingoo Han <[email protected]>
+
+properties:
+  compatible:
+    const: pwm-backlight
+
+  pwms:
+    maxItems: 1
+
+  pwm-names: true
+
+  power-supply:
+    description: regulator for supply voltage
+
+  enable-gpios:
+    description: Contains a single GPIO specifier for the GPIO which enables
+      and disables the backlight
+    maxItems: 1
+
+  post-pwm-on-delay-ms:
+    description: Delay in ms between setting an initial (non-zero) PWM and
+      enabling the backlight using GPIO.
+
+  pwm-off-delay-ms:
+    description: Delay in ms between disabling the backlight using GPIO
+      and setting PWM value to 0.
+
+  brightness-levels:
+    description: Array of distinct brightness levels. Typically these are
+      in the range from 0 to 255, but any range starting at 0 will do. The
+      actual brightness level (PWM duty cycle) will be interpolated from
+      these values. 0 means a 0% duty cycle (darkest/off), while the last

Quoted 8 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml line 50

Quoted 7 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +7 -0

+      value in the array represents a 100% duty cycle (brightest).
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+
+  default-brightness-level:
+    description: The default brightness level (index into the array defined
+      by the "brightness-levels" property).
+    $ref: /schemas/types.yaml#/definitions/uint32

Same comment as before...

Sorry the "ditto" meant I didn't thing about PWM as much as I should have.

The situation for PWM is a little different to LED. That's mostly because we decided not to clutter the LED code with "num-interpolated-steps".

The PWM code implements the default-brightness-level as an index into the brightness array *after* it has been expanded using interpolation. In other words today Linux treats the default-brightness-level more like[1].

description: The default brightness level. When
num-interpolated-steps is not set this is simply an index into the array defined by the "brightness-levels" property. If num-interpolated-steps is set the brightness array will be expanded by interpolation before we index to get a default level.

Quoted 2 lines

This is the best I have come up with so far... but I concede it still lacks elegance.

Happy to add this or whatever folks want if there's agreement, but I don't want to get bogged down on re-reviewing and re-writing the binding on what is just a conversion. There's a mountain of bindings to convert.

Quoted 84 lines · Rob Herring

Quoted 81 lines · Daniel Thompson

Quoted 49 lines · Sam Ravnborg

Quoted 49 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +43 -0

new file mode 100644
index 000000000000..7e1f109a38a4
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/pwm-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: pwm-backlight bindings
+
+maintainers:
+  - Lee Jones <[email protected]>
+  - Daniel Thompson <[email protected]>
+  - Jingoo Han <[email protected]>
+
+properties:
+  compatible:
+    const: pwm-backlight
+
+  pwms:
+    maxItems: 1
+
+  pwm-names: true
+
+  power-supply:
+    description: regulator for supply voltage
+
+  enable-gpios:
+    description: Contains a single GPIO specifier for the GPIO which enables
+      and disables the backlight
+    maxItems: 1
+
+  post-pwm-on-delay-ms:
+    description: Delay in ms between setting an initial (non-zero) PWM and
+      enabling the backlight using GPIO.
+
+  pwm-off-delay-ms:
+    description: Delay in ms between disabling the backlight using GPIO
+      and setting PWM value to 0.
+
+  brightness-levels:
+    description: Array of distinct brightness levels. Typically these are
+      in the range from 0 to 255, but any range starting at 0 will do. The
+      actual brightness level (PWM duty cycle) will be interpolated from
+      these values. 0 means a 0% duty cycle (darkest/off), while the last

Quoted 8 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml line 50

Quoted 7 lines

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +7 -0

+      value in the array represents a 100% duty cycle (brightest).
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+
+  default-brightness-level:
+    description: The default brightness level (index into the array defined
+      by the "brightness-levels" property).
+    $ref: /schemas/types.yaml#/definitions/uint32

Same comment as before...

Sorry the "ditto" meant I didn't thing about PWM as much as I should have.

The situation for PWM is a little different to LED. That's mostly because we decided not to clutter the LED code with "num-interpolated-steps".

The PWM code implements the default-brightness-level as an index into the brightness array *after* it has been expanded using interpolation. In other words today Linux treats the default-brightness-level more like[1].

description: The default brightness level. When
num-interpolated-steps is not set this is simply an index into the array defined by the "brightness-levels" property. If num-interpolated-steps is set the brightness array will be expanded by interpolation before we index to get a default level.

This is the best I have come up with so far... but I concede it still lacks elegance.

Quoted 4 lines

Happy to add this or whatever folks want if there's agreement, but I don't want to get bogged down on re-reviewing and re-writing the binding on what is just a conversion. There's a mountain of bindings to convert.

The original explanation is ok, as pointed out by Daniel. So I suggest moving forward with that and then others can improve the descriptions later as necessary.

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

Quoted 162 lines · Rob Herring

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 <[email protected]>

Cc Daniel Thompson <[email protected]>

Cc Jingoo Han <[email protected]>

Signed-off-by Rob Herring <[email protected]>

---
 .../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

Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt deleted +0 -16

deleted file mode 100644
index 321be6640533..000000000000
@@ -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;
-     };

Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml new file +41 -0

new file mode 100644
index 000000000000..75cc569b9c55
@@ -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 <[email protected]>
+  - Daniel Thompson <[email protected]>
+  - Jingoo Han <[email protected]>
+
+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;
+    };
+
+...

Documentation/devicetree/bindings/leds/backlight/led-backlight.txt deleted +0 -28

deleted file mode 100644
index 4c7dfbe7f67a..000000000000
@@ -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>;
-     };

Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml new file +28 -0

new file mode 100644
index 000000000000..ae50945d2798
@@ -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 <[email protected]>
+  - Daniel Thompson <[email protected]>
+  - Jingoo Han <[email protected]>
+
+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

Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml line 32

Quoted 4 lines

Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml new file +4 -0

+      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.

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 <[email protected]>

Cc Daniel Thompson <[email protected]>

Cc Jingoo Han <[email protected]>

Signed-off-by Rob Herring <[email protected]>

Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml new file +30 -0

new file mode 100644
index 000000000000..ae50945d2798
@@ -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 <[email protected]>
+  - Daniel Thompson <[email protected]>
+  - Jingoo Han <[email protected]>
+
+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.

Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file +50 -0

new file mode 100644
index 000000000000..7e1f109a38a4
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/pwm-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: pwm-backlight bindings
+
+maintainers:
+  - Lee Jones <[email protected]>
+  - Daniel Thompson <[email protected]>
+  - Jingoo Han <[email protected]>
+
+properties:
+  compatible:
+    const: pwm-backlight
+
+  pwms:
+    maxItems: 1
+
+  pwm-names: true
+
+  power-supply:
+    description: regulator for supply voltage
+
+  enable-gpios:
+    description: Contains a single GPIO specifier for the GPIO which enables
+      and disables the backlight
+    maxItems: 1
+
+  post-pwm-on-delay-ms:
+    description: Delay in ms between setting an initial (non-zero) PWM and
+      enabling the backlight using GPIO.
+
+  pwm-off-delay-ms:
+    description: Delay in ms between disabling the backlight using GPIO
+      and setting PWM value to 0.
+
+  brightness-levels:
+    description: Array of distinct brightness levels. Typically these are
+      in the range from 0 to 255, but any range starting at 0 will do. The
+      actual brightness level (PWM duty cycle) will be interpolated from
+      these values. 0 means a 0% duty cycle (darkest/off), while the last
+      value in the array represents a 100% duty cycle (brightest).
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+
+  default-brightness-level:
+    description: The default brightness level (index into the array defined
+      by the "brightness-levels" property).
+    $ref: /schemas/types.yaml#/definitions/uint32