Documentation/devicetree/bindings/leds/common.txt

   1 * Common leds properties.
   2
   3 LED and flash LED devices provide the same basic functionality as current
   4 regulators, but extended with LED and flash LED specific features like
   5 blinking patterns, flash timeout, flash faults and external flash strobe mode.
   6
   7 Many LED devices expose more than one current output that can be connected
   8 to one or more discrete LED component. Since the arrangement of connections
   9 can influence the way of the LED device initialization, the LED components
  10 have to be tightly coupled with the LED device binding. They are represented
  11 by child nodes of the parent LED device binding.
  12
  13
  14 Optional properties for child nodes:
  15 - led-sources : List of device current outputs the LED is connected to. The
  16                 outputs are identified by the numbers that must be defined
  17                 in the LED device binding documentation.
  18
  19 - function: LED functon. Use one of the LED_FUNCTION_* prefixed definitions
  20             from the header include/dt-bindings/leds/common.h.
  21             If there is no matching LED_FUNCTION available, add a new one.
  22
  23 - color : Color of the LED. Use one of the LED_COLOR_ID_* prefixed definitions
  24           from the header include/dt-bindings/leds/common.h.
  25           If there is no matching LED_COLOR_ID available, add a new one.
  26
  27 - function-enumerator: Integer to be used when more than one instance
  28                        of the same function is needed, differing only with
  29                        an ordinal number.
  30
  31 - label : The label for this LED. If omitted, the label is taken from the node
  32           name (excluding the unit address). It has to uniquely identify
  33           a device, i.e. no other LED class device can be assigned the same
  34           label. This property is deprecated - use 'function' and 'color'
  35           properties instead. function-enumerator has no effect when this
  36           property is present.
  37
  38 - default-state : The initial state of the LED. Valid values are "on", "off",
  39   and "keep". If the LED is already on or off and the default-state property is
  40   set the to same value, then no glitch should be produced where the LED
  41   momentarily turns off (or on). The "keep" setting will keep the LED at
  42   whatever its current state is, without producing a glitch.  The default is
  43   off if this property is not present.
  44
  45 - linux,default-trigger :  This parameter, if present, is a
  46     string defining the trigger assigned to the LED.  Current triggers are:
  47      "backlight" - LED will act as a back-light, controlled by the framebuffer
  48                    system
  49      "default-on" - LED will turn on (but for leds-gpio see "default-state"
  50                     property in Documentation/devicetree/bindings/leds/leds-gpio.txt)
  51      "heartbeat" - LED "double" flashes at a load average based rate
  52      "disk-activity" - LED indicates disk activity
  53      "ide-disk" - LED indicates IDE disk activity (deprecated),
  54                   in new implementations use "disk-activity"
  55      "timer" - LED flashes at a fixed, configurable rate
  56      "pattern" - LED alters the brightness for the specified duration with one
  57                  software timer (requires "led-pattern" property)
  58
  59 - led-pattern : Array of integers with default pattern for certain triggers.
  60                 Each trigger may parse this property differently:
  61                 - one-shot : two numbers specifying delay on and delay off (in ms),
  62                 - timer : two numbers specifying delay on and delay off (in ms),
  63                 - pattern : the pattern is given by a series of tuples, of
  64                   brightness and duration (in ms).  The exact format is
  65                   described in:
  66                   Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt
  67
  68
  69 - led-max-microamp : Maximum LED supply current in microamperes. This property
  70                      can be made mandatory for the board configurations
  71                      introducing a risk of hardware damage in case an excessive
  72                      current is set.
  73                      For flash LED controllers with configurable current this
  74                      property is mandatory for the LEDs in the non-flash modes
  75                      (e.g. torch or indicator).
  76
  77 - panic-indicator : This property specifies that the LED should be used,
  78                     if at all possible, as a panic indicator.
  79
  80 - trigger-sources : List of devices which should be used as a source triggering
  81                     this LED activity. Some LEDs can be related to a specific
  82                     device and should somehow indicate its state. E.g. USB 2.0
  83                     LED may react to device(s) in a USB 2.0 port(s).
  84                     Another common example is switch or router with multiple
  85                     Ethernet ports each of them having its own LED assigned
  86                     (assuming they are not hardwired). In such cases this
  87                     property should contain phandle(s) of related source
  88                     device(s).
  89                     In many cases LED can be related to more than one device
  90                     (e.g. one USB LED vs. multiple USB ports). Each source
  91                     should be represented by a node in the device tree and be
  92                     referenced by a phandle and a set of phandle arguments. A
  93                     length of arguments should be specified by the
  94                     #trigger-source-cells property in the source node.
  95
  96 Required properties for flash LED child nodes:
  97 - flash-max-microamp : Maximum flash LED supply current in microamperes.
  98 - flash-max-timeout-us : Maximum timeout in microseconds after which the flash
  99                          LED is turned off.
 100
 101 For controllers that have no configurable current the flash-max-microamp
 102 property can be omitted.
 103 For controllers that have no configurable timeout the flash-max-timeout-us
 104 property can be omitted.
 105
 106 * Trigger source providers
 107
 108 Each trigger source should be represented by a device tree node. It may be e.g.
 109 a USB port or an Ethernet device.
 110
 111 Required properties for trigger source:
 112 - #trigger-source-cells : Number of cells in a source trigger. Typically 0 for
 113                           nodes of simple trigger sources (e.g. a specific USB
 114                           port).
 115
 116 * Examples
 117
 118 #include <dt-bindings/leds/common.h>
 119
 120 led-controller@0 {
 121         compatible = "gpio-leds";
 122
 123         led0 {
 124                 function = LED_FUNCTION_STATUS;
 125                 linux,default-trigger = "heartbeat";
 126                 gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
 127         };
 128
 129         led1 {
 130                 function = LED_FUNCTION_USB;
 131                 gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
 132                 trigger-sources = <&ohci_port1>, <&ehci_port1>;
 133         };
 134 };
 135
 136 led-controller@0 {
 137         compatible = "maxim,max77693-led";
 138
 139         led {
 140                 function = LED_FUNCTION_FLASH;
 141                 color = <LED_COLOR_ID_WHITE>;
 142                 led-sources = <0>, <1>;
 143                 led-max-microamp = <50000>;
 144                 flash-max-microamp = <320000>;
 145                 flash-max-timeout-us = <500000>;
 146         };
 147 };
 148
 149 led-controller@30 {
 150         compatible = "panasonic,an30259a";
 151         reg = <0x30>;
 152         #address-cells = <1>;
 153         #size-cells = <0>;
 154
 155         led@1 {
 156                 reg = <1>;
 157                 linux,default-trigger = "heartbeat";
 158                 function = LED_FUNCTION_INDICATOR;
 159                 function-enumerator = <1>;
 160         };
 161
 162         led@2 {
 163                 reg = <2>;
 164                 function = LED_FUNCTION_INDICATOR;
 165                 function-enumerator = <2>;
 166         };
 167
 168         led@3 {
 169                 reg = <3>;
 170                 function = LED_FUNCTION_INDICATOR;
 171                 function-enumerator = <3>;
 172         };
 173 };