dt-bindings: leds: Convert LP8860 into YAML format

From: Alexander Sverdlin <alexander.sverdlin@siemens.com>

Convert Texas Instruments' LP8860 LED driver bindings into YAML format.

Signed-off-by: Alexander Sverdlin <alexander.sverdlin@siemens.com>
---
The patch is now separated from the LP8864 series:
https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20241206170717.1090206-2-alexander.sverdlin@siemens.com/

 .../devicetree/bindings/leds/leds-lp8860.txt  | 50 ----------
 .../devicetree/bindings/leds/ti,lp8860.yaml   | 95 +++++++++++++++++++
 2 files changed, 95 insertions(+), 50 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/leds/leds-lp8860.txt
 create mode 100644 Documentation/devicetree/bindings/leds/ti,lp8860.yaml

Hi Andrew,

thanks for the prompt review!

On Mon, 2024-12-09 at 08:29 -0600, Andrew Davis wrote:
> > +  reg:
> > +    maxItems: 1
> > +    description: I2C slave address
> > +
> > +  "#address-cells":
> > +    const: 1
> > +
> > +  "#size-cells":
> > +    const: 0
> > +
> > +  enable-gpios:
> > +    maxItems: 1
> > +    description: GPIO pin to enable (active high) / disable the device
> > +
> > +  vled-supply:
> > +    description: LED supply
> > +
> > +patternProperties:
> > +  "^led@[0]$":
> > +    type: object
> > +    $ref: common.yaml#
> > +    unevaluatedProperties: false
> > +
> > +    properties:
> > +      reg:
> > +        description:
> > +          Index of the LED.
> > +        const: 0
> > +
> > +      function: true
> > +      color: true
> > +      label: true
> > +      linux,default-trigger: true
> > +
> > +    required:
> > +      - reg
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - "#address-cells"
> > +  - "#size-cells"
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/gpio/gpio.h>
> > +    #include <dt-bindings/leds/common.h>
> > +
> > +    i2c {
> > +        #address-cells = <1>;
> > +        #size-cells = <0>;
> > +
> > +        led-controller@2d {
> > +            compatible = "ti,lp8860";
> > +            #address-cells = <1>;
> > +            #size-cells = <0>;
> > +            reg = <0x2d>;
> > +            enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>;
> > +            vled-supply = <&vbatt>;
> > +
> > +            led@0 {
> 
> So same comment I made in the pre-public review, lets see what the DT
> folks think:
> 
> I don't think we want to have the "@0" node naming. It forces us to
> add the "reg =" below, and that then forces us to add the #*-cells above.
> All this to work around not just calling the node "led-0". The driver
> doesn't care either way, and there are no in-tree users of the old way,
> so now should be a safe time to fix this while converting the binding.

If I understood you correctly here:

>> And one channel controlling the others is only in this "Display Mode",
>> but the currents to the others can be independently controlled in a
>> different mode (seems these modes have less features which is probably
>> why the driver doesn't make use of that today).

then some mapping between subnode and HW channel would be required.
We probably don't want to parse a node name in this case and carve out "-0"
part of it, in such case a well-defined property, such as "reg" would be
required.

So preserving the status quo looks more future-proof IMO.

Hi Andrew!

On Mon, 2024-12-09 at 09:05 -0600, Andrew Davis wrote:
> > then some mapping between subnode and HW channel would be required.
> > We probably don't want to parse a node name in this case and carve out "-0"
> > part of it, in such case a well-defined property, such as "reg" would be
> > required.
> > 
> 
> We are not the only driver to do the "-#" method. Although yes just
> using reg is easier for the Linux driver.

After a quick grep over the bindings I'd say those led-X are using
"gpios" or "pwms" property to associate them with real HW and seems that
there is exactly one example of doing some implicit mapping: nxp,pca953x.yaml

It seems to me that using "reg" is much more widespread (if it's neither "gpios"
nor "pwms").

On Mon, Dec 09, 2024 at 08:29:00AM -0600, Andrew Davis wrote:
> On 12/6/24 2:31 PM, A. Sverdlin wrote:
> > From: Alexander Sverdlin <alexander.sverdlin@siemens.com>
> > 
> > Convert Texas Instruments' LP8860 LED driver bindings into YAML format.
> > 
> > Signed-off-by: Alexander Sverdlin <alexander.sverdlin@siemens.com>
> > ---
> > The patch is now separated from the LP8864 series:
> > https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20241206170717.1090206-2-alexander.sverdlin@siemens.com/
> > 
> >   .../devicetree/bindings/leds/leds-lp8860.txt  | 50 ----------
> >   .../devicetree/bindings/leds/ti,lp8860.yaml   | 95 +++++++++++++++++++
> >   2 files changed, 95 insertions(+), 50 deletions(-)
> >   delete mode 100644 Documentation/devicetree/bindings/leds/leds-lp8860.txt
> >   create mode 100644 Documentation/devicetree/bindings/leds/ti,lp8860.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt
> > deleted file mode 100644
> > index 8bb25749a3da3..0000000000000
> > --- a/Documentation/devicetree/bindings/leds/leds-lp8860.txt
> > +++ /dev/null
> > @@ -1,50 +0,0 @@
> > -* Texas Instruments - lp8860 4-Channel LED Driver
> > -
> > -The LP8860-Q1 is an high-efficiency LED
> > -driver with boost controller. It has 4 high-precision
> > -current sinks that can be controlled by a PWM input
> > -signal, a SPI/I2C master, or both.
> > -
> > -Required properties:
> > -	- compatible :
> > -		"ti,lp8860"
> > -	- reg : I2C slave address
> > -	- #address-cells : 1
> > -	- #size-cells : 0
> > -
> > -Optional properties:
> > -	- enable-gpios : gpio pin to enable (active high)/disable the device.
> > -	- vled-supply : LED supply
> > -
> > -Required child properties:
> > -	- reg : 0
> > -
> > -Optional child properties:
> > -	- function : see Documentation/devicetree/bindings/leds/common.txt
> > -	- color : see Documentation/devicetree/bindings/leds/common.txt
> > -	- label : see Documentation/devicetree/bindings/leds/common.txt (deprecated)
> > -	- linux,default-trigger :
> > -	   see Documentation/devicetree/bindings/leds/common.txt
> > -
> > -Example:
> > -
> > -#include <dt-bindings/leds/common.h>
> > -
> > -led-controller@2d {
> > -	compatible = "ti,lp8860";
> > -	#address-cells = <1>;
> > -	#size-cells = <0>;
> > -	reg = <0x2d>;
> > -	enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>;
> > -	vled-supply = <&vbatt>;
> > -
> > -	led@0 {
> > -		reg = <0>;
> > -		function = LED_FUNCTION_BACKLIGHT;
> > -		color = <LED_COLOR_ID_WHITE>;
> > -		linux,default-trigger = "backlight";
> > -	};
> > -}
> > -
> > -For more product information please see the link below:
> > -https://www.ti.com/product/lp8860-q1
> > diff --git a/Documentation/devicetree/bindings/leds/ti,lp8860.yaml b/Documentation/devicetree/bindings/leds/ti,lp8860.yaml
> > new file mode 100644
> > index 0000000000000..62f133006fd0e
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/leds/ti,lp8860.yaml
> > @@ -0,0 +1,95 @@
> > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/leds/ti,lp8860.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Texas Instruments - lp8860 4-Channel LED Driver
> > +
> > +maintainers:
> > +  - Andrew Davis <afd@ti.com>
> > +
> > +description: |
> > +  The LP8860-Q1 is an high-efficiency LED driver with boost controller.
> > +  It has 4 high-precision current sinks that can be controlled by a PWM input
> > +  signal, a SPI/I2C master, or both.
> > +
> > +  For more product information please see the link below:
> > +    https://www.ti.com/product/lp8860-q1
> > +
> > +properties:
> > +  compatible:
> > +    const: ti,lp8860
> > +
> > +  reg:
> > +    maxItems: 1
> > +    description: I2C slave address
> > +
> > +  "#address-cells":
> > +    const: 1
> > +
> > +  "#size-cells":
> > +    const: 0
> > +
> > +  enable-gpios:
> > +    maxItems: 1
> > +    description: GPIO pin to enable (active high) / disable the device
> > +
> > +  vled-supply:
> > +    description: LED supply
> > +
> > +patternProperties:
> > +  "^led@[0]$":
> > +    type: object
> > +    $ref: common.yaml#
> > +    unevaluatedProperties: false
> > +
> > +    properties:
> > +      reg:
> > +        description:
> > +          Index of the LED.
> > +        const: 0
> > +
> > +      function: true
> > +      color: true
> > +      label: true
> > +      linux,default-trigger: true
> > +
> > +    required:
> > +      - reg
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - "#address-cells"
> > +  - "#size-cells"
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/gpio/gpio.h>
> > +    #include <dt-bindings/leds/common.h>
> > +
> > +    i2c {
> > +        #address-cells = <1>;
> > +        #size-cells = <0>;
> > +
> > +        led-controller@2d {
> > +            compatible = "ti,lp8860";
> > +            #address-cells = <1>;
> > +            #size-cells = <0>;
> > +            reg = <0x2d>;
> > +            enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>;
> > +            vled-supply = <&vbatt>;
> > +
> > +            led@0 {
> 
> So same comment I made in the pre-public review, lets see what the DT
> folks think:
> 
> I don't think we want to have the "@0" node naming. It forces us to
> add the "reg =" below, and that then forces us to add the #*-cells above.
> All this to work around not just calling the node "led-0". The driver
> doesn't care either way, and there are no in-tree users of the old way,
> so now should be a safe time to fix this while converting the binding.

Just 'led' should be allowed for the single child case.

However, as there are 4 channels, shouldn't the schema be '^led@[0-3]$'? 
If you want to support both that and just 'led', then that can be done 
too.

Rob