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     allOf:
  45       - $ref: /schemas/types.yaml#definitions/uint32
  46     minimum: 0
  47     maximum: 8
  48
  49   function-enumerator:
  50     description:
  51       Integer to be used when more than one instance of the same function is
  52       needed, differing only with an ordinal number.
  53     $ref: /schemas/types.yaml#definitions/uint32
  54
  55   label:
  56     description:
  57       The label for this LED. If omitted, the label is taken from the node name
  58       (excluding the unit address). It has to uniquely identify a device, i.e.
  59       no other LED class device can be assigned the same label. This property is
  60       deprecated - use 'function' and 'color' properties instead.
  61       function-enumerator has no effect when this property is present.
  62
  63   default-state:
  64     description:
  65       The initial state of the LED. If the LED is already on or off and the
  66       default-state property is set the to same value, then no glitch should be
  67       produced where the LED momentarily turns off (or on). The "keep" setting
  68       will keep the LED at whatever its current state is, without producing a
  69       glitch.
  70     allOf:
  71       - $ref: /schemas/types.yaml#definitions/string
  72     enum:
  73       - on
  74       - off
  75       - keep
  76     default: off
  77
  78   linux,default-trigger:
  79     description:
  80       This parameter, if present, is a string defining the trigger assigned to
  81       the LED.
  82     allOf:
  83       - $ref: /schemas/types.yaml#definitions/string
  84     enum:
  85         # LED will act as a back-light, controlled by the framebuffer system
  86       - backlight
  87         # LED will turn on (but for leds-gpio see "default-state" property in
  88         # Documentation/devicetree/bindings/leds/leds-gpio.yaml)
  89       - default-on
  90         # LED "double" flashes at a load average based rate
  91       - heartbeat
  92         # LED indicates disk activity
  93       - disk-activity
  94         # LED indicates IDE disk activity (deprecated), in new implementations
  95         # use "disk-activity"
  96       - ide-disk
  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
 103   led-pattern:
 104     description: |
 105       Array of integers with default pattern for certain triggers.
 106
 107       Each trigger may parse this property differently:
 108         - one-shot : two numbers specifying delay on and delay off (in ms),
 109         - timer : two numbers specifying delay on and delay off (in ms),
 110         - pattern : the pattern is given by a series of tuples, of
 111           brightness and duration (in ms).  The exact format is
 112           described in:
 113           Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt
 114     allOf:
 115       - $ref: /schemas/types.yaml#definitions/uint32-matrix
 116     items:
 117       minItems: 2
 118       maxItems: 2
 119
 120   led-max-microamp:
 121     description:
 122       Maximum LED supply current in microamperes. This property can be made
 123       mandatory for the board configurations introducing a risk of hardware
 124       damage in case an excessive current is set.
 125       For flash LED controllers with configurable current this property is
 126       mandatory for the LEDs in the non-flash modes (e.g. torch or indicator).
 127
 128   panic-indicator:
 129     description:
 130       This property specifies that the LED should be used, if at all possible,
 131       as a panic indicator.
 132     type: boolean
 133
 134   trigger-sources:
 135     description: |
 136       List of devices which should be used as a source triggering this LED
 137       activity. Some LEDs can be related to a specific device and should somehow
 138       indicate its state. E.g. USB 2.0 LED may react to device(s) in a USB 2.0
 139       port(s).
 140       Another common example is switch or router with multiple Ethernet ports
 141       each of them having its own LED assigned (assuming they are not
 142       hardwired). In such cases this property should contain phandle(s) of
 143       related source device(s).
 144       In many cases LED can be related to more than one device (e.g. one USB LED
 145       vs. multiple USB ports). Each source should be represented by a node in
 146       the device tree and be referenced by a phandle and a set of phandle
 147       arguments. A length of arguments should be specified by the
 148       #trigger-source-cells property in the source node.
 149     $ref: /schemas/types.yaml#definitions/phandle-array
 150
 151   # Required properties for flash LED child nodes:
 152   flash-max-microamp:
 153     description:
 154       Maximum flash LED supply current in microamperes. Required for flash LED
 155       nodes with configurable current.
 156
 157   flash-max-timeout-us:
 158     description:
 159       Maximum timeout in microseconds after which the flash LED is turned off.
 160       Required for flash LED nodes with configurable timeout.
 161
 162 examples:
 163   - |
 164     #include <dt-bindings/gpio/gpio.h>
 165     #include <dt-bindings/leds/common.h>
 166
 167     led-controller {
 168         compatible = "gpio-leds";
 169
 170         led-0 {
 171             function = LED_FUNCTION_STATUS;
 172             linux,default-trigger = "heartbeat";
 173             gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
 174         };
 175
 176         led-1 {
 177             function = LED_FUNCTION_USB;
 178             gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
 179             trigger-sources = <&ohci_port1>, <&ehci_port1>;
 180         };
 181     };
 182
 183     led-controller@0 {
 184         compatible = "maxim,max77693-led";
 185         reg = <0 0x100>;
 186
 187         led {
 188             function = LED_FUNCTION_FLASH;
 189             color = <LED_COLOR_ID_WHITE>;
 190             led-sources = <0>, <1>;
 191             led-max-microamp = <50000>;
 192             flash-max-microamp = <320000>;
 193             flash-max-timeout-us = <500000>;
 194         };
 195     };
 196
 197     i2c {
 198         #address-cells = <1>;
 199         #size-cells = <0>;
 200
 201         led-controller@30 {
 202             compatible = "panasonic,an30259a";
 203             reg = <0x30>;
 204             #address-cells = <1>;
 205             #size-cells = <0>;
 206
 207             led@1 {
 208                 reg = <1>;
 209                 linux,default-trigger = "heartbeat";
 210                 function = LED_FUNCTION_INDICATOR;
 211                 function-enumerator = <1>;
 212             };
 213
 214             led@2 {
 215                 reg = <2>;
 216                 function = LED_FUNCTION_INDICATOR;
 217                 function-enumerator = <2>;
 218             };
 219
 220             led@3 {
 221                 reg = <3>;
 222                 function = LED_FUNCTION_INDICATOR;
 223                 function-enumerator = <3>;
 224             };
 225         };
 226     };
 227
 228 ...