[PATCH 0/1] dt-bindings: mfd: add ti,lm8502 LED + haptic controller

[PATCH 0/1] dt-bindings: mfd: add ti,lm8502 LED + haptic controller

[Herman van Hazendonk]

Add a YAML binding for the TI LM8502, an I2C combo LED + haptic
controller used in the HP TouchPad (MSM8x60 / APQ8060) tablet.

The LM8502 exposes ten constant-current LED outputs (D1..D10) and an
internal H-bridge for driving a vibrator motor. Pin D10 is shared
between the tenth LED channel and the haptic output; the haptic child
driver mux's D10 to the H-bridge path at each FF_RUMBLE event.

The device is modelled as an MFD with two child sub-nodes:

  ti,lm8502-leds   - LED-class outputs D1..D10 (per-LED reg +
                     led-max-microamp properties)
  ti,lm8502-haptic - EV_FF / FF_RUMBLE input device for the
                     internal H-bridge, with optional
                     ti,invert-direction property

The MFD core driver was already sent separately:
  "[PATCH v2 0/1] mfd: lm8502: add core MFD driver for TI LM8502"
  Message-ID: <20260603040026.398009-1-github.com@herrie.org>

Child drivers (leds-lm8502, input-lm8502-haptic) will follow as
separate series once the binding and core are accepted.

Herman van Hazendonk (1):
  dt-bindings: mfd: add ti,lm8502 combo LED + haptic controller

 .../devicetree/bindings/mfd/ti,lm8502.yaml    | 160 ++++++++++++++++++
 1 file changed, 160 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mfd/ti,lm8502.yaml

-- 
2.43.0

[PATCH 1/1] dt-bindings: mfd: add ti,lm8502 combo LED + haptic controller

[Herman van Hazendonk]

Add a YAML binding for the TI LM8502, an I2C combo LED + haptic
controller used in the HP TouchPad tablet. The chip is exposed as an
MFD with two child sub-nodes:

  ti,lm8502-leds   - LED-class outputs D1..D10 (with per-LED reg
                     and led-max-microamp properties)
  ti,lm8502-haptic - EV_FF / FF_RUMBLE input device for the internal
                     H-bridge vibrator output, optional
                     ti,invert-direction property

Signed-off-by: Herman van Hazendonk <github.com@herrie.org>
---
 .../devicetree/bindings/mfd/ti,lm8502.yaml    | 160 ++++++++++++++++++
 1 file changed, 160 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mfd/ti,lm8502.yaml

diff --git a/Documentation/devicetree/bindings/mfd/ti,lm8502.yaml b/Documentation/devicetree/bindings/mfd/ti,lm8502.yaml
new file mode 100644
index 000000000000..10f2e32a0738
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/ti,lm8502.yaml
@@ -0,0 +1,160 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mfd/ti,lm8502.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI LM8502 combo LED + haptic controller
+
+maintainers:
+  - Herman van Hazendonk <github.com@herrie.org>
+
+description: |
+  The TI LM8502 is an I2C combo device with ten constant-current LED
+  outputs (D1..D10) and an internal H-bridge that drives a vibrator
+  motor. Pin D10 is shared between the tenth LED channel and the
+  haptic output; the haptic driver writes D10_CURRENT_CTRL = 0 at each
+  start to mux the pin to the H-bridge path.
+
+  The chip is exposed in Linux as an MFD with two children:
+    - ti,lm8502-leds   - LED-class outputs D1..D10
+    - ti,lm8502-haptic - EV_FF / FF_RUMBLE input device
+
+  The parent node owns the I2C client, the chip-enable GPIO and the
+  vcc regulator; children share access to the parent's regmap.
+
+properties:
+  compatible:
+    const: ti,lm8502
+
+  reg:
+    maxItems: 1
+
+  vcc-supply:
+    description:
+      Power supply for the chip (V_DD). On platforms where this supply
+      is provided by an RPM-managed LDO with "regulator-allow-set-load",
+      the driver will request High Power Mode (~100 mA) so the internal
+      boost converter and ten LED outputs are not current-starved.
+
+  enable-gpios:
+    maxItems: 1
+    description:
+      GPIO connected to the chip-enable pin. Pulled high by the driver
+      at probe time and dropped low across PM suspend.
+
+  pinctrl-names: true
+  pinctrl-0: true
+
+  leds:
+    type: object
+    additionalProperties: false
+    description: LED-class child for outputs D1..D10.
+
+    properties:
+      compatible:
+        const: ti,lm8502-leds
+
+      '#address-cells':
+        const: 1
+
+      '#size-cells':
+        const: 0
+
+    patternProperties:
+      '^led@[0-9]$':
+        type: object
+        $ref: /schemas/leds/common.yaml#
+        unevaluatedProperties: false
+
+        properties:
+          reg:
+            description:
+              Zero-based D-channel index (0 = D1 .. 9 = D10).
+            minimum: 0
+            maximum: 9
+
+          led-max-microamp:
+            description: |
+              Per-channel current cap. The chip's MAX_CURRENT field
+              quantises this to one of four buckets:
+                <=3000  - 3 mA
+                <=6000  - 6 mA
+                <=9000  - 9 mA  (default)
+                 >9000  - 12.75 mA
+            default: 9000
+
+        required:
+          - reg
+
+    required:
+      - compatible
+
+  haptic:
+    type: object
+    additionalProperties: false
+    description: FF_RUMBLE child for the internal H-bridge vibrator output.
+
+    properties:
+      compatible:
+        const: ti,lm8502-haptic
+
+      ti,invert-direction:
+        type: boolean
+        description:
+          Flip the H-bridge polarity bit in HAPTIC_FEEDBACK_CTRL so the
+          motor spins in the direction the board expects.
+
+    required:
+      - compatible
+
+required:
+  - compatible
+  - reg
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+    #include <dt-bindings/leds/common.h>
+
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        led-controller@33 {
+            compatible = "ti,lm8502";
+            reg = <0x33>;
+
+            vcc-supply = <&pm8058_l16>;
+            enable-gpios = <&tlmm 121 GPIO_ACTIVE_HIGH>;
+
+            leds {
+                compatible = "ti,lm8502-leds";
+                #address-cells = <1>;
+                #size-cells = <0>;
+
+                led@0 {
+                    reg = <0>;
+                    label = "lm8502:white:navi_left";
+                    color = <LED_COLOR_ID_WHITE>;
+                    function = LED_FUNCTION_INDICATOR;
+                    led-max-microamp = <9000>;
+                };
+
+                led@1 {
+                    reg = <1>;
+                    label = "lm8502:white:navi_right";
+                    color = <LED_COLOR_ID_WHITE>;
+                    function = LED_FUNCTION_INDICATOR;
+                    led-max-microamp = <9000>;
+                };
+            };
+
+            haptic {
+                compatible = "ti,lm8502-haptic";
+                ti,invert-direction;
+            };
+        };
+    };
-- 
2.43.0

Re: [PATCH 1/1] dt-bindings: mfd: add ti,lm8502 combo LED + haptic controller

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Medium] The binding describes Linux driver internals (MFD structure) rather than hardware layout by creating artificial 'leds' and 'haptic' sub-nodes.
--

commit 25934ec50a44a98662b56dfb64e70a785820fdf7
Author: Herman van Hazendonk <github.com@herrie.org>

dt-bindings: mfd: add ti,lm8502 combo LED + haptic controller

This commit adds a new YAML device tree binding for the TI LM8502, an I2C
combo LED and haptic controller. The device exposes its LED and haptic
functionalities as sub-nodes of the main I2C device.

> diff --git a/Documentation/devicetree/bindings/mfd/ti,lm8502.yaml b/Documentation/devicetree/bindings/mfd/ti,lm8502.yaml
> new file mode 100644
> index 0000000000000..10f2e32a07385
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/ti,lm8502.yaml
> @@ -0,0 +1,160 @@
[ ... ]
> +description: |
> +  The TI LM8502 is an I2C combo device with ten constant-current LED
> +  outputs (D1..D10) and an internal H-bridge that drives a vibrator
> +  motor. Pin D10 is shared between the tenth LED channel and the
> +  haptic output; the haptic driver writes D10_CURRENT_CTRL = 0 at each
> +  start to mux the pin to the H-bridge path.
> +
> +  The chip is exposed in Linux as an MFD with two children:
> +    - ti,lm8502-leds   - LED-class outputs D1..D10
> +    - ti,lm8502-haptic - EV_FF / FF_RUMBLE input device

[Severity: Medium]
Does this description rely too heavily on Linux driver internals rather than
hardware layout?

Device tree bindings should generally model the physical hardware structure.
Describing how the OS software stack divides the MFD subsystems creates
long-term maintenance debt since DT bindings form a stable hardware
description ABI.

> +
> +  The parent node owns the I2C client, the chip-enable GPIO and the
> +  vcc regulator; children share access to the parent's regmap.
> +
> +properties:
> +  compatible:
> +    const: ti,lm8502
[ ... ]
> +  leds:
> +    type: object
> +    additionalProperties: false
> +    description: LED-class child for outputs D1..D10.
> +
> +    properties:
> +      compatible:
> +        const: ti,lm8502-leds

[Severity: Medium]
Is the ti,lm8502-leds compatible string strictly necessary for hardware
description?

Creating artificial sub-nodes with their own software-specific compatible
strings just to force driver matching for the Linux MFD framework violates
devicetree design principles.

The sub-functions should typically be represented as properties or direct
child nodes of the parent device without requiring separate compatible
strings, unless they are genuinely independently reusable IP blocks.

[ ... ]
> +  haptic:
> +    type: object
> +    additionalProperties: false
> +    description: FF_RUMBLE child for the internal H-bridge vibrator output.
> +
> +    properties:
> +      compatible:
> +        const: ti,lm8502-haptic

[Severity: Medium]
Similar to the leds sub-node, would it be possible to omit this artificial
compatible string and represent the haptic function without a dedicated
software-specific node?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260603080256.853037-1-github.com@herrie.org?part=1

Re: [PATCH 1/1] dt-bindings: mfd: add ti,lm8502 combo LED + haptic controller

[Herman van Hazendonk]

Thank you for the review feedback.

Acknowledged — the ti,lm8502-leds / ti,lm8502-haptic compatible strings
are a Linux MFD driver artifact rather than a hardware description. The
description text also mentions the OS split, which should be removed.

Before preparing v2 I wanted to ask how you would prefer this structured:

Option A — LP55xx style (no sub-node compatibles):
Individual led@N nodes (reg 0..9 = D1..D10) go directly on the parent,
following leds-lp55xx.yaml. The haptic function is a plain haptic sub-node
(config container for ti,invert-direction) with no compatible. The parent
driver instantiates children via mfd_cells[] keyed on platform device name;
DT parsing is done in the parent driver. This requires companion changes to
the MFD core and child drivers.

Option B — Single flat node:
Fold everything into the parent node. LED channels and haptic described via
properties directly on the I2C device node, no sub-nodes at all. Simpler
binding, but per-LED led-max-microamp config becomes a list property rather
than per-node, which is less readable for a 10-channel device.

My inclination is Option A as it matches the LP55xx precedent, but happy to
follow your preference or any third approach you have in mind.

Signed-off-by: Herman van Hazendonk <github.com@herrie.org>