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     enum:
  83         # LED will act as a back-light, controlled by the framebuffer system
  84       - backlight
  85         # LED will turn on (but for leds-gpio see "default-state" property in
  86         # Documentation/devicetree/bindings/leds/leds-gpio.yaml)
  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 IDE disk activity (deprecated), in new implementations
  93         # use "disk-activity"
  94       - ide-disk
  95         # LED flashes at a fixed, configurable rate
  96       - timer
  97         # LED alters the brightness for the specified duration with one software
  98         # timer (requires "led-pattern" property)
  99       - pattern
 100
 101   led-pattern:
 102     description: |
 103       Array of integers with default pattern for certain triggers.
 104
 105       Each trigger may parse this property differently:
 106         - one-shot : two numbers specifying delay on and delay off (in ms),
 107         - timer : two numbers specifying delay on and delay off (in ms),
 108         - pattern : the pattern is given by a series of tuples, of
 109           brightness and duration (in ms).  The exact format is
 110           described in:
 111           Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt
 112     $ref: /schemas/types.yaml#/definitions/uint32-matrix
 113     items:
 114       minItems: 2
 115       maxItems: 2
 116
 117   led-max-microamp:
 118     description:
 119       Maximum LED supply current in microamperes. This property can be made
 120       mandatory for the board configurations introducing a risk of hardware
 121       damage in case an excessive current is set.
 122       For flash LED controllers with configurable current this property is
 123       mandatory for the LEDs in the non-flash modes (e.g. torch or indicator).
 124
 125   panic-indicator:
 126     description:
 127       This property specifies that the LED should be used, if at all possible,
 128       as a panic indicator.
 129     type: boolean
 130
 131   trigger-sources:
 132     description: |
 133       List of devices which should be used as a source triggering this LED
 134       activity. Some LEDs can be related to a specific device and should somehow
 135       indicate its state. E.g. USB 2.0 LED may react to device(s) in a USB 2.0
 136       port(s).
 137       Another common example is switch or router with multiple Ethernet ports
 138       each of them having its own LED assigned (assuming they are not
 139       hardwired). In such cases this property should contain phandle(s) of
 140       related source device(s).
 141       In many cases LED can be related to more than one device (e.g. one USB LED
 142       vs. multiple USB ports). Each source should be represented by a node in
 143       the device tree and be referenced by a phandle and a set of phandle
 144       arguments. A length of arguments should be specified by the
 145       #trigger-source-cells property in the source node.
 146     $ref: /schemas/types.yaml#/definitions/phandle-array
 147
 148   # Required properties for flash LED child nodes:
 149   flash-max-microamp:
 150     description:
 151       Maximum flash LED supply current in microamperes. Required for flash LED
 152       nodes with configurable current.
 153
 154   flash-max-timeout-us:
 155     description:
 156       Maximum timeout in microseconds after which the flash LED is turned off.
 157       Required for flash LED nodes with configurable timeout.
 158
 159 additionalProperties: true
 160
 161 examples:
 162   - |
 163     #include <dt-bindings/gpio/gpio.h>
 164     #include <dt-bindings/leds/common.h>
 165
 166     led-controller {
 167         compatible = "gpio-leds";
 168
 169         led-0 {
 170             function = LED_FUNCTION_STATUS;
 171             linux,default-trigger = "heartbeat";
 172             gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
 173         };
 174
 175         led-1 {
 176             function = LED_FUNCTION_USB;
 177             gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
 178             trigger-sources = <&ohci_port1>, <&ehci_port1>;
 179         };
 180     };
 181
 182     led-controller@0 {
 183         compatible = "maxim,max77693-led";
 184         reg = <0 0x100>;
 185
 186         led {
 187             function = LED_FUNCTION_FLASH;
 188             color = <LED_COLOR_ID_WHITE>;
 189             led-sources = <0>, <1>;
 190             led-max-microamp = <50000>;
 191             flash-max-microamp = <320000>;
 192             flash-max-timeout-us = <500000>;
 193         };
 194     };
 195
 196     i2c {
 197         #address-cells = <1>;
 198         #size-cells = <0>;
 199
 200         led-controller@30 {
 201             compatible = "panasonic,an30259a";
 202             reg = <0x30>;
 203             #address-cells = <1>;
 204             #size-cells = <0>;
 205
 206             led@1 {
 207                 reg = <1>;
 208                 linux,default-trigger = "heartbeat";
 209                 function = LED_FUNCTION_INDICATOR;
 210                 function-enumerator = <1>;
 211             };
 212
 213             led@2 {
 214                 reg = <2>;
 215                 function = LED_FUNCTION_INDICATOR;
 216                 function-enumerator = <2>;
 217             };
 218
 219             led@3 {
 220                 reg = <3>;
 221                 function = LED_FUNCTION_INDICATOR;
 222                 function-enumerator = <3>;
 223             };
 224         };
 225     };
 226
 227 ...