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: 9
  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 (but for leds-gpio see "default-state" property in
  87             # Documentation/devicetree/bindings/leds/leds-gpio.yaml)
  88           - default-on
  89             # LED "double" flashes at a load average based rate
  90           - heartbeat
  91             # LED indicates disk activity
  92           - disk-activity
  93             # LED indicates disk read activity
  94           - disk-read
  95             # LED indicates disk write activity
  96           - disk-write
  97             # LED flashes at a fixed, configurable rate
  98           - timer
  99             # LED alters the brightness for the specified duration with one software
 100             # timer (requires "led-pattern" property)
 101           - pattern
 102             # LED indicates mic mute state
 103           - audio-micmute
 104             # LED indicates audio mute state
 105           - audio-mute
 106             # LED indicates bluetooth power state
 107           - bluetooth-power
 108             # LED indicates activity of all CPUs
 109           - cpu
 110             # LED indicates camera flash state
 111           - flash
 112             # LED indicated keyboard capslock
 113           - kbd-capslock
 114             # LED indicates MTD memory activity
 115           - mtd
 116             # LED indicates NAND memory activity (deprecated),
 117             # in new implementations use "mtd"
 118           - nand-disk
 119             # No trigger assigned to the LED. This is the default mode
 120             # if trigger is absent
 121           - none
 122             # LED indicates camera torch state
 123           - torch
 124             # LED indicates USB gadget activity
 125           - usb-gadget
 126             # LED indicates USB host activity
 127           - usb-host
 128         # LED is triggered by CPU activity
 129       - pattern: "^cpu[0-9]*$"
 130         # LED is triggered by Bluetooth activity
 131       - pattern: "^hci[0-9]+-power$"
 132         # LED is triggered by SD/MMC activity
 133       - pattern: "^mmc[0-9]+$"
 134         # LED is triggered by WLAN activity
 135       - pattern: "^phy[0-9]+tx$"
 136
 137   led-pattern:
 138     description: |
 139       Array of integers with default pattern for certain triggers.
 140
 141       Each trigger may parse this property differently:
 142         - one-shot : two numbers specifying delay on and delay off (in ms),
 143         - timer : two numbers specifying delay on and delay off (in ms),
 144         - pattern : the pattern is given by a series of tuples, of
 145           brightness and duration (in ms).  The exact format is
 146           described in:
 147           Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt
 148     $ref: /schemas/types.yaml#/definitions/uint32-matrix
 149     items:
 150       minItems: 2
 151       maxItems: 2
 152
 153   led-max-microamp:
 154     description:
 155       Maximum LED supply current in microamperes. This property can be made
 156       mandatory for the board configurations introducing a risk of hardware
 157       damage in case an excessive current is set.
 158       For flash LED controllers with configurable current this property is
 159       mandatory for the LEDs in the non-flash modes (e.g. torch or indicator).
 160
 161   panic-indicator:
 162     description:
 163       This property specifies that the LED should be used, if at all possible,
 164       as a panic indicator.
 165     type: boolean
 166
 167   retain-state-shutdown:
 168     description:
 169       This property specifies that the LED should not be turned off or changed
 170       when the system shuts down.
 171     type: boolean
 172
 173   trigger-sources:
 174     description: |
 175       List of devices which should be used as a source triggering this LED
 176       activity. Some LEDs can be related to a specific device and should somehow
 177       indicate its state. E.g. USB 2.0 LED may react to device(s) in a USB 2.0
 178       port(s).
 179       Another common example is switch or router with multiple Ethernet ports
 180       each of them having its own LED assigned (assuming they are not
 181       hardwired). In such cases this property should contain phandle(s) of
 182       related source device(s).
 183       In many cases LED can be related to more than one device (e.g. one USB LED
 184       vs. multiple USB ports). Each source should be represented by a node in
 185       the device tree and be referenced by a phandle and a set of phandle
 186       arguments. A length of arguments should be specified by the
 187       #trigger-source-cells property in the source node.
 188     $ref: /schemas/types.yaml#/definitions/phandle-array
 189
 190   # Required properties for flash LED child nodes:
 191   flash-max-microamp:
 192     description:
 193       Maximum flash LED supply current in microamperes. Required for flash LED
 194       nodes with configurable current.
 195
 196   flash-max-timeout-us:
 197     description:
 198       Maximum timeout in microseconds after which the flash LED is turned off.
 199       Required for flash LED nodes with configurable timeout.
 200
 201 additionalProperties: true
 202
 203 examples:
 204   - |
 205     #include <dt-bindings/gpio/gpio.h>
 206     #include <dt-bindings/leds/common.h>
 207
 208     led-controller {
 209         compatible = "gpio-leds";
 210
 211         led-0 {
 212             function = LED_FUNCTION_STATUS;
 213             linux,default-trigger = "heartbeat";
 214             gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
 215         };
 216
 217         led-1 {
 218             function = LED_FUNCTION_USB;
 219             gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
 220             trigger-sources = <&ohci_port1>, <&ehci_port1>;
 221         };
 222     };
 223
 224   - |
 225     #include <dt-bindings/leds/common.h>
 226
 227     led-controller {
 228         compatible = "maxim,max77693-led";
 229
 230         led {
 231             function = LED_FUNCTION_FLASH;
 232             color = <LED_COLOR_ID_WHITE>;
 233             led-sources = <0>, <1>;
 234             led-max-microamp = <50000>;
 235             flash-max-microamp = <320000>;
 236             flash-max-timeout-us = <500000>;
 237         };
 238     };
 239
 240   - |
 241     #include <dt-bindings/leds/common.h>
 242
 243     i2c {
 244         #address-cells = <1>;
 245         #size-cells = <0>;
 246
 247         led-controller@30 {
 248             compatible = "panasonic,an30259a";
 249             reg = <0x30>;
 250             #address-cells = <1>;
 251             #size-cells = <0>;
 252
 253             led@1 {
 254                 reg = <1>;
 255                 linux,default-trigger = "heartbeat";
 256                 function = LED_FUNCTION_INDICATOR;
 257                 function-enumerator = <1>;
 258             };
 259
 260             led@2 {
 261                 reg = <2>;
 262                 function = LED_FUNCTION_INDICATOR;
 263                 function-enumerator = <2>;
 264             };
 265
 266             led@3 {
 267                 reg = <3>;
 268                 function = LED_FUNCTION_INDICATOR;
 269                 function-enumerator = <3>;
 270             };
 271         };
 272     };
 273
 274 ...