Documentation/devicetree/bindings/leds/common.yaml

   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
   7 title: Common leds properties
   8
   9 maintainers:
  10   - Jacek Anaszewski <jacek.anaszewski@gmail.com>
  11   - Pavel Machek <pavel@ucw.cz>
  12
  13 description:
  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
  24 properties:
  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             # No trigger assigned to the LED. This is the default mode
 117             # if trigger is absent
 118           - none
 119             # LED indicates camera torch state
 120           - torch
 121             # LED indicates USB gadget activity
 122           - usb-gadget
 123             # LED indicates USB host activity
 124           - usb-host
 125             # LED indicates USB port state
 126           - usbport
 127         # LED is triggered by CPU activity
 128       - pattern: "^cpu[0-9]*$"
 129         # LED is triggered by Bluetooth activity
 130       - pattern: "^hci[0-9]+-power$"
 131         # LED is triggered by SD/MMC activity
 132       - pattern: "^mmc[0-9]+$"
 133         # LED is triggered by WLAN activity
 134       - pattern: "^phy[0-9]+tx$"
 135
 136   led-pattern:
 137     description: |
 138       Array of integers with default pattern for certain triggers.
 139
 140       Each trigger may parse this property differently:
 141         - one-shot : two numbers specifying delay on and delay off (in ms),
 142         - timer : two numbers specifying delay on and delay off (in ms),
 143         - pattern : the pattern is given by a series of tuples, of
 144           brightness and duration (in ms).  The exact format is
 145           described in:
 146           Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt
 147     $ref: /schemas/types.yaml#/definitions/uint32-matrix
 148     items:
 149       minItems: 2
 150       maxItems: 2
 151
 152   led-max-microamp:
 153     description:
 154       Maximum LED supply current in microamperes. This property can be made
 155       mandatory for the board configurations introducing a risk of hardware
 156       damage in case an excessive current is set.
 157       For flash LED controllers with configurable current this property is
 158       mandatory for the LEDs in the non-flash modes (e.g. torch or indicator).
 159
 160   max-brightness:
 161     description:
 162       Normally, the maximum brightness is determined by the hardware, and this
 163       property is not required. This property is used to set a software limit.
 164       It could happen that an LED is made so bright that it gets damaged or
 165       causes damage due to restrictions in a specific system, such as mounting
 166       conditions.
 167       Note that this flag is mainly used for PWM-LEDs, where it is not possible
 168       to map brightness to current. Drivers for other controllers should use
 169       led-max-microamp.
 170     $ref: /schemas/types.yaml#/definitions/uint32
 171
 172   panic-indicator:
 173     description:
 174       This property specifies that the LED should be used, if at all possible,
 175       as a panic indicator.
 176     type: boolean
 177
 178   retain-state-shutdown:
 179     description:
 180       This property specifies that the LED should not be turned off or changed
 181       when the system shuts down.
 182     type: boolean
 183
 184   trigger-sources:
 185     description: |
 186       List of devices which should be used as a source triggering this LED
 187       activity. Some LEDs can be related to a specific device and should somehow
 188       indicate its state. E.g. USB 2.0 LED may react to device(s) in a USB 2.0
 189       port(s).
 190       Another common example is switch or router with multiple Ethernet ports
 191       each of them having its own LED assigned (assuming they are not
 192       hardwired). In such cases this property should contain phandle(s) of
 193       related source device(s).
 194       Another example is a GPIO line that will be monitored and mirror the
 195       state of the line (with or without inversion flags) to the LED.
 196       In many cases LED can be related to more than one device (e.g. one USB LED
 197       vs. multiple USB ports). Each source should be represented by a node in
 198       the device tree and be referenced by a phandle and a set of phandle
 199       arguments. A length of arguments should be specified by the
 200       #trigger-source-cells property in the source node.
 201     $ref: /schemas/types.yaml#/definitions/phandle-array
 202
 203   active-low:
 204     type: boolean
 205     description:
 206       Makes LED active low. To turn the LED ON, line needs to be
 207       set to low voltage instead of high.
 208
 209   inactive-high-impedance:
 210     type: boolean
 211     description:
 212       Set LED to high-impedance mode to turn the LED OFF. LED might also
 213       describe this mode as tristate.
 214
 215   # Required properties for flash LED child nodes:
 216   flash-max-microamp:
 217     description:
 218       Maximum flash LED supply current in microamperes. Required for flash LED
 219       nodes with configurable current.
 220
 221   flash-max-timeout-us:
 222     description:
 223       Maximum timeout in microseconds after which the flash LED is turned off.
 224       Required for flash LED nodes with configurable timeout.
 225
 226 additionalProperties: true
 227
 228 examples:
 229   - |
 230     #include <dt-bindings/gpio/gpio.h>
 231     #include <dt-bindings/leds/common.h>
 232
 233     led-controller {
 234         compatible = "gpio-leds";
 235
 236         led-0 {
 237             function = LED_FUNCTION_STATUS;
 238             linux,default-trigger = "heartbeat";
 239             gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
 240         };
 241
 242         led-1 {
 243             function = LED_FUNCTION_USB;
 244             gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
 245             trigger-sources = <&ohci_port1>, <&ehci_port1>;
 246         };
 247     };
 248
 249   - |
 250     #include <dt-bindings/leds/common.h>
 251
 252     led-controller {
 253         compatible = "maxim,max77693-led";
 254
 255         led {
 256             function = LED_FUNCTION_FLASH;
 257             color = <LED_COLOR_ID_WHITE>;
 258             led-sources = <0>, <1>;
 259             led-max-microamp = <50000>;
 260             flash-max-microamp = <320000>;
 261             flash-max-timeout-us = <500000>;
 262         };
 263     };
 264
 265   - |
 266     #include <dt-bindings/leds/common.h>
 267
 268     i2c {
 269         #address-cells = <1>;
 270         #size-cells = <0>;
 271
 272         led-controller@30 {
 273             compatible = "panasonic,an30259a";
 274             reg = <0x30>;
 275             #address-cells = <1>;
 276             #size-cells = <0>;
 277
 278             led@1 {
 279                 reg = <1>;
 280                 linux,default-trigger = "heartbeat";
 281                 function = LED_FUNCTION_INDICATOR;
 282                 function-enumerator = <1>;
 283             };
 284
 285             led@2 {
 286                 reg = <2>;
 287                 function = LED_FUNCTION_INDICATOR;
 288                 function-enumerator = <2>;
 289             };
 290
 291             led@3 {
 292                 reg = <3>;
 293                 function = LED_FUNCTION_INDICATOR;
 294                 function-enumerator = <3>;
 295             };
 296         };
 297     };
 298
 299 ...