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 IDE disk activity (deprecated), in new implementations
  94             # use "disk-activity"
  95           - ide-disk
  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 is triggered by SD/MMC activity
 102       - pattern: "^mmc[0-9]+$"
 103
 104   led-pattern:
 105     description: |
 106       Array of integers with default pattern for certain triggers.
 107
 108       Each trigger may parse this property differently:
 109         - one-shot : two numbers specifying delay on and delay off (in ms),
 110         - timer : two numbers specifying delay on and delay off (in ms),
 111         - pattern : the pattern is given by a series of tuples, of
 112           brightness and duration (in ms).  The exact format is
 113           described in:
 114           Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt
 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   retain-state-shutdown:
 135     description:
 136       This property specifies that the LED should not be turned off or changed
 137       when the system shuts down.
 138     type: boolean
 139
 140   trigger-sources:
 141     description: |
 142       List of devices which should be used as a source triggering this LED
 143       activity. Some LEDs can be related to a specific device and should somehow
 144       indicate its state. E.g. USB 2.0 LED may react to device(s) in a USB 2.0
 145       port(s).
 146       Another common example is switch or router with multiple Ethernet ports
 147       each of them having its own LED assigned (assuming they are not
 148       hardwired). In such cases this property should contain phandle(s) of
 149       related source device(s).
 150       In many cases LED can be related to more than one device (e.g. one USB LED
 151       vs. multiple USB ports). Each source should be represented by a node in
 152       the device tree and be referenced by a phandle and a set of phandle
 153       arguments. A length of arguments should be specified by the
 154       #trigger-source-cells property in the source node.
 155     $ref: /schemas/types.yaml#/definitions/phandle-array
 156
 157   # Required properties for flash LED child nodes:
 158   flash-max-microamp:
 159     description:
 160       Maximum flash LED supply current in microamperes. Required for flash LED
 161       nodes with configurable current.
 162
 163   flash-max-timeout-us:
 164     description:
 165       Maximum timeout in microseconds after which the flash LED is turned off.
 166       Required for flash LED nodes with configurable timeout.
 167
 168 additionalProperties: true
 169
 170 examples:
 171   - |
 172     #include <dt-bindings/gpio/gpio.h>
 173     #include <dt-bindings/leds/common.h>
 174
 175     led-controller {
 176         compatible = "gpio-leds";
 177
 178         led-0 {
 179             function = LED_FUNCTION_STATUS;
 180             linux,default-trigger = "heartbeat";
 181             gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
 182         };
 183
 184         led-1 {
 185             function = LED_FUNCTION_USB;
 186             gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
 187             trigger-sources = <&ohci_port1>, <&ehci_port1>;
 188         };
 189     };
 190
 191   - |
 192     #include <dt-bindings/leds/common.h>
 193
 194     led-controller {
 195         compatible = "maxim,max77693-led";
 196
 197         led {
 198             function = LED_FUNCTION_FLASH;
 199             color = <LED_COLOR_ID_WHITE>;
 200             led-sources = <0>, <1>;
 201             led-max-microamp = <50000>;
 202             flash-max-microamp = <320000>;
 203             flash-max-timeout-us = <500000>;
 204         };
 205     };
 206
 207   - |
 208     #include <dt-bindings/leds/common.h>
 209
 210     i2c {
 211         #address-cells = <1>;
 212         #size-cells = <0>;
 213
 214         led-controller@30 {
 215             compatible = "panasonic,an30259a";
 216             reg = <0x30>;
 217             #address-cells = <1>;
 218             #size-cells = <0>;
 219
 220             led@1 {
 221                 reg = <1>;
 222                 linux,default-trigger = "heartbeat";
 223                 function = LED_FUNCTION_INDICATOR;
 224                 function-enumerator = <1>;
 225             };
 226
 227             led@2 {
 228                 reg = <2>;
 229                 function = LED_FUNCTION_INDICATOR;
 230                 function-enumerator = <2>;
 231             };
 232
 233             led@3 {
 234                 reg = <3>;
 235                 function = LED_FUNCTION_INDICATOR;
 236                 function-enumerator = <3>;
 237             };
 238         };
 239     };
 240
 241 ...