xref: /linux/Documentation/devicetree/bindings/leds/common.yaml (revision 93251bdf7a771c4eeb0f95fa38ded92e95154ef7)
1# SPDX-License-Identifier: GPL-2.0-only
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/leds/common.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: Common leds properties
8
9maintainers:
10  - Jacek Anaszewski <jacek.anaszewski@gmail.com>
11  - Pavel Machek <pavel@ucw.cz>
12
13description:
14  LED and flash LED devices provide the same basic functionality as current
15  regulators, but extended with LED and flash LED specific features like
16  blinking patterns, flash timeout, flash faults and external flash strobe mode.
17
18  Many LED devices expose more than one current output that can be connected
19  to one or more discrete LED component. Since the arrangement of connections
20  can influence the way of the LED device initialization, the LED components
21  have to be tightly coupled with the LED device binding. They are represented
22  by child nodes of the parent LED device binding.
23
24properties:
25  led-sources:
26    description:
27      List of device current outputs the LED is connected to. The outputs are
28      identified by the numbers that must be defined in the LED device binding
29      documentation.
30    $ref: /schemas/types.yaml#/definitions/uint32-array
31
32  function:
33    description:
34      LED function. Use one of the LED_FUNCTION_* prefixed definitions
35      from the header include/dt-bindings/leds/common.h. If there is no
36      matching LED_FUNCTION available, add a new one.
37    $ref: /schemas/types.yaml#/definitions/string
38
39  color:
40    description:
41      Color of the LED. Use one of the LED_COLOR_ID_* prefixed definitions from
42      the header include/dt-bindings/leds/common.h. If there is no matching
43      LED_COLOR_ID available, add a new one.
44    $ref: /schemas/types.yaml#/definitions/uint32
45    minimum: 0
46    maximum: 14
47
48  function-enumerator:
49    description:
50      Integer to be used when more than one instance of the same function is
51      needed, differing only with an ordinal number.
52    $ref: /schemas/types.yaml#/definitions/uint32
53
54  label:
55    description:
56      The label for this LED. If omitted, the label is taken from the node name
57      (excluding the unit address). It has to uniquely identify a device, i.e.
58      no other LED class device can be assigned the same label. This property is
59      deprecated - use 'function' and 'color' properties instead.
60      function-enumerator has no effect when this property is present.
61
62  default-state:
63    description:
64      The initial state of the LED. If the LED is already on or off and the
65      default-state property is set the to same value, then no glitch should be
66      produced where the LED momentarily turns off (or on). The "keep" setting
67      will keep the LED at whatever its current state is, without producing a
68      glitch.
69    $ref: /schemas/types.yaml#/definitions/string
70    enum:
71      - on
72      - off
73      - keep
74    default: off
75
76  linux,default-trigger:
77    description:
78      This parameter, if present, is a string defining the trigger assigned to
79      the LED.
80    $ref: /schemas/types.yaml#/definitions/string
81
82    oneOf:
83      - enum:
84            # LED will act as a back-light, controlled by the framebuffer system
85          - backlight
86            # LED will turn on (see also "default-state" property)
87          - default-on
88            # LED "double" flashes at a load average based rate
89          - heartbeat
90            # LED indicates disk activity
91          - disk-activity
92            # LED indicates disk read activity
93          - disk-read
94            # LED indicates disk write activity
95          - disk-write
96            # LED flashes at a fixed, configurable rate
97          - timer
98            # LED alters the brightness for the specified duration with one software
99            # timer (requires "led-pattern" property)
100          - pattern
101            # LED indicates mic mute state
102          - audio-micmute
103            # LED indicates audio mute state
104          - audio-mute
105            # LED indicates bluetooth power state
106          - bluetooth-power
107            # LED indicates camera flash state
108          - flash
109            # LED indicated keyboard capslock
110          - kbd-capslock
111            # LED indicates MTD memory activity
112          - mtd
113            # LED indicates NAND memory activity (deprecated),
114            # in new implementations use "mtd"
115          - nand-disk
116            # LED indicates network activity
117          - netdev
118            # No trigger assigned to the LED. This is the default mode
119            # if trigger is absent
120          - none
121            # LED indicates remote control feedback
122          - rc-feedback
123            # LED indicates camera torch state
124          - torch
125            # LED indicates USB gadget activity
126          - usb-gadget
127            # LED indicates USB host activity
128          - usb-host
129            # LED indicates USB port state
130          - usbport
131        # LED is triggered by CPU activity
132      - pattern: "^cpu[0-9]*$"
133        # LED is triggered by Bluetooth activity
134      - pattern: "^hci[0-9]+-power$"
135        # LED is triggered by SD/MMC activity
136      - pattern: "^mmc[0-9]+$"
137        # LED is triggered by WLAN activity
138      - pattern: "^phy[0-9]+tx$"
139
140  led-pattern:
141    description: |
142      Array of integers with default pattern for certain triggers.
143
144      Each trigger may parse this property differently:
145        - one-shot : two numbers specifying delay on and delay off (in ms),
146        - timer : two numbers specifying delay on and delay off (in ms),
147        - pattern : the pattern is given by a series of tuples, of
148          brightness and duration (in ms).  The exact format is
149          described in:
150          Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt
151    $ref: /schemas/types.yaml#/definitions/uint32-matrix
152    items:
153      minItems: 2
154      maxItems: 2
155
156  led-max-microamp:
157    description:
158      Maximum LED supply current in microamperes. This property can be made
159      mandatory for the board configurations introducing a risk of hardware
160      damage in case an excessive current is set.
161      For flash LED controllers with configurable current this property is
162      mandatory for the LEDs in the non-flash modes (e.g. torch or indicator).
163
164  max-brightness:
165    description:
166      Normally, the maximum brightness is determined by the hardware, and this
167      property is not required. This property is used to set a software limit.
168      It could happen that an LED is made so bright that it gets damaged or
169      causes damage due to restrictions in a specific system, such as mounting
170      conditions.
171      Note that this flag is mainly used for PWM-LEDs, where it is not possible
172      to map brightness to current. Drivers for other controllers should use
173      led-max-microamp.
174    $ref: /schemas/types.yaml#/definitions/uint32
175
176  panic-indicator:
177    description:
178      This property specifies that the LED should be used, if at all possible,
179      as a panic indicator.
180    type: boolean
181
182  retain-state-shutdown:
183    description:
184      This property specifies that the LED should not be turned off or changed
185      when the system shuts down.
186    type: boolean
187
188  trigger-sources:
189    description: |
190      List of devices which should be used as a source triggering this LED
191      activity. Some LEDs can be related to a specific device and should somehow
192      indicate its state. E.g. USB 2.0 LED may react to device(s) in a USB 2.0
193      port(s).
194      Another common example is switch or router with multiple Ethernet ports
195      each of them having its own LED assigned (assuming they are not
196      hardwired). In such cases this property should contain phandle(s) of
197      related source device(s).
198      Another example is a GPIO line that will be monitored and mirror the
199      state of the line (with or without inversion flags) to the LED.
200      In many cases LED can be related to more than one device (e.g. one USB LED
201      vs. multiple USB ports). Each source should be represented by a node in
202      the device tree and be referenced by a phandle and a set of phandle
203      arguments. A length of arguments should be specified by the
204      #trigger-source-cells property in the source node.
205    $ref: /schemas/types.yaml#/definitions/phandle-array
206
207  active-high:
208    type: boolean
209    description:
210      Makes LED active high. To turn the LED ON, line needs to be
211      set to high voltage instead of low.
212
213  active-low:
214    type: boolean
215    description:
216      Makes LED active low. To turn the LED ON, line needs to be
217      set to low voltage instead of high.
218
219  inactive-high-impedance:
220    type: boolean
221    description:
222      Set LED to high-impedance mode to turn the LED OFF. LED might also
223      describe this mode as tristate.
224
225  # Required properties for flash LED child nodes:
226  flash-max-microamp:
227    description:
228      Maximum flash LED supply current in microamperes. Required for flash LED
229      nodes with configurable current.
230
231  flash-max-timeout-us:
232    description:
233      Maximum timeout in microseconds after which the flash LED is turned off.
234      Required for flash LED nodes with configurable timeout.
235
236allOf:
237  - if:
238      required:
239        - active-low
240    then:
241      properties:
242        active-high: false
243
244additionalProperties: true
245
246examples:
247  - |
248    #include <dt-bindings/gpio/gpio.h>
249    #include <dt-bindings/leds/common.h>
250
251    led-controller {
252        compatible = "gpio-leds";
253
254        led-0 {
255            function = LED_FUNCTION_STATUS;
256            linux,default-trigger = "heartbeat";
257            gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
258        };
259
260        led-1 {
261            function = LED_FUNCTION_USB;
262            gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
263            trigger-sources = <&ohci_port1>, <&ehci_port1>;
264        };
265    };
266
267  - |
268    #include <dt-bindings/leds/common.h>
269
270    led-controller {
271        compatible = "maxim,max77693-led";
272
273        led {
274            function = LED_FUNCTION_FLASH;
275            color = <LED_COLOR_ID_WHITE>;
276            led-sources = <0>, <1>;
277            led-max-microamp = <50000>;
278            flash-max-microamp = <320000>;
279            flash-max-timeout-us = <500000>;
280        };
281    };
282
283  - |
284    #include <dt-bindings/leds/common.h>
285
286    i2c {
287        #address-cells = <1>;
288        #size-cells = <0>;
289
290        led-controller@30 {
291            compatible = "panasonic,an30259a";
292            reg = <0x30>;
293            #address-cells = <1>;
294            #size-cells = <0>;
295
296            led@1 {
297                reg = <1>;
298                linux,default-trigger = "heartbeat";
299                function = LED_FUNCTION_INDICATOR;
300                function-enumerator = <1>;
301            };
302
303            led@2 {
304                reg = <2>;
305                function = LED_FUNCTION_INDICATOR;
306                function-enumerator = <2>;
307            };
308
309            led@3 {
310                reg = <3>;
311                function = LED_FUNCTION_INDICATOR;
312                function-enumerator = <3>;
313            };
314        };
315    };
316
317...
318