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