[thirdparty/u-boot.git] / Bindings / leds / common.yaml

# SPDX-License-Identifier: GPL-2.0-only
%YAML 1.2
---
$id: http://devicetree.org/schemas/leds/common.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Common leds properties

maintainers:
  - Jacek Anaszewski <jacek.anaszewski@gmail.com>
  - Pavel Machek <pavel@ucw.cz>

description:
  LED and flash LED devices provide the same basic functionality as current
  regulators, but extended with LED and flash LED specific features like
  blinking patterns, flash timeout, flash faults and external flash strobe mode.

  Many LED devices expose more than one current output that can be connected
  to one or more discrete LED component. Since the arrangement of connections
  can influence the way of the LED device initialization, the LED components
  have to be tightly coupled with the LED device binding. They are represented
  by child nodes of the parent LED device binding.

properties:
  led-sources:
    description:
      List of device current outputs the LED is connected to. The outputs are
      identified by the numbers that must be defined in the LED device binding
      documentation.
    $ref: /schemas/types.yaml#/definitions/uint32-array

  function:
    description:
      LED function. Use one of the LED_FUNCTION_* prefixed definitions
      from the header include/dt-bindings/leds/common.h. If there is no
      matching LED_FUNCTION available, add a new one.
    $ref: /schemas/types.yaml#/definitions/string

  color:
    description:
      Color of the LED. Use one of the LED_COLOR_ID_* prefixed definitions from
      the header include/dt-bindings/leds/common.h. If there is no matching
      LED_COLOR_ID available, add a new one.
    $ref: /schemas/types.yaml#/definitions/uint32
    minimum: 0
    maximum: 14

  function-enumerator:
    description:
      Integer to be used when more than one instance of the same function is
      needed, differing only with an ordinal number.
    $ref: /schemas/types.yaml#/definitions/uint32

  label:
    description:
      The label for this LED. If omitted, the label is taken from the node name
      (excluding the unit address). It has to uniquely identify a device, i.e.
      no other LED class device can be assigned the same label. This property is
      deprecated - use 'function' and 'color' properties instead.
      function-enumerator has no effect when this property is present.

  default-state:
    description:
      The initial state of the LED. If the LED is already on or off and the
      default-state property is set the to same value, then no glitch should be
      produced where the LED momentarily turns off (or on). The "keep" setting
      will keep the LED at whatever its current state is, without producing a
      glitch.
    $ref: /schemas/types.yaml#/definitions/string
    enum:
      - on
      - off
      - keep
    default: off

  linux,default-trigger:
    description:
      This parameter, if present, is a string defining the trigger assigned to
      the LED.
    $ref: /schemas/types.yaml#/definitions/string

    oneOf:
      - enum:
            # LED will act as a back-light, controlled by the framebuffer system
          - backlight
            # LED will turn on (see also "default-state" property)
          - default-on
            # LED "double" flashes at a load average based rate
          - heartbeat
            # LED indicates disk activity
          - disk-activity
            # LED indicates disk read activity
          - disk-read
            # LED indicates disk write activity
          - disk-write
            # LED flashes at a fixed, configurable rate
          - timer
            # LED alters the brightness for the specified duration with one software
            # timer (requires "led-pattern" property)
          - pattern
            # LED indicates mic mute state
          - audio-micmute
            # LED indicates audio mute state
          - audio-mute
            # LED indicates bluetooth power state
          - bluetooth-power
            # LED indicates camera flash state
          - flash
            # LED indicated keyboard capslock
          - kbd-capslock
            # LED indicates MTD memory activity
          - mtd
            # LED indicates NAND memory activity (deprecated),
            # in new implementations use "mtd"
          - nand-disk
            # No trigger assigned to the LED. This is the default mode
            # if trigger is absent
          - none
            # LED indicates camera torch state
          - torch
            # LED indicates USB gadget activity
          - usb-gadget
            # LED indicates USB host activity
          - usb-host
            # LED indicates USB port state
          - usbport
        # LED is triggered by CPU activity
      - pattern: "^cpu[0-9]*$"
        # LED is triggered by Bluetooth activity
      - pattern: "^hci[0-9]+-power$"
        # LED is triggered by SD/MMC activity
      - pattern: "^mmc[0-9]+$"
        # LED is triggered by WLAN activity
      - pattern: "^phy[0-9]+tx$"

  led-pattern:
    description: |
      Array of integers with default pattern for certain triggers.

      Each trigger may parse this property differently:
        - one-shot : two numbers specifying delay on and delay off (in ms),
        - timer : two numbers specifying delay on and delay off (in ms),
        - pattern : the pattern is given by a series of tuples, of
          brightness and duration (in ms).  The exact format is
          described in:
          Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt
    $ref: /schemas/types.yaml#/definitions/uint32-matrix
    items:
      minItems: 2
      maxItems: 2

  led-max-microamp:
    description:
      Maximum LED supply current in microamperes. This property can be made
      mandatory for the board configurations introducing a risk of hardware
      damage in case an excessive current is set.
      For flash LED controllers with configurable current this property is
      mandatory for the LEDs in the non-flash modes (e.g. torch or indicator).

  max-brightness:
    description:
      Normally, the maximum brightness is determined by the hardware, and this
      property is not required. This property is used to set a software limit.
      It could happen that an LED is made so bright that it gets damaged or
      causes damage due to restrictions in a specific system, such as mounting
      conditions.
      Note that this flag is mainly used for PWM-LEDs, where it is not possible
      to map brightness to current. Drivers for other controllers should use
      led-max-microamp.
    $ref: /schemas/types.yaml#/definitions/uint32

  panic-indicator:
    description:
      This property specifies that the LED should be used, if at all possible,
      as a panic indicator.
    type: boolean

  retain-state-shutdown:
    description:
      This property specifies that the LED should not be turned off or changed
      when the system shuts down.
    type: boolean

  trigger-sources:
    description: |
      List of devices which should be used as a source triggering this LED
      activity. Some LEDs can be related to a specific device and should somehow
      indicate its state. E.g. USB 2.0 LED may react to device(s) in a USB 2.0
      port(s).
      Another common example is switch or router with multiple Ethernet ports
      each of them having its own LED assigned (assuming they are not
      hardwired). In such cases this property should contain phandle(s) of
      related source device(s).
      Another example is a GPIO line that will be monitored and mirror the
      state of the line (with or without inversion flags) to the LED.
      In many cases LED can be related to more than one device (e.g. one USB LED
      vs. multiple USB ports). Each source should be represented by a node in
      the device tree and be referenced by a phandle and a set of phandle
      arguments. A length of arguments should be specified by the
      #trigger-source-cells property in the source node.
    $ref: /schemas/types.yaml#/definitions/phandle-array

  # Required properties for flash LED child nodes:
  flash-max-microamp:
    description:
      Maximum flash LED supply current in microamperes. Required for flash LED
      nodes with configurable current.

  flash-max-timeout-us:
    description:
      Maximum timeout in microseconds after which the flash LED is turned off.
      Required for flash LED nodes with configurable timeout.

additionalProperties: true

examples:
  - |
    #include <dt-bindings/gpio/gpio.h>
    #include <dt-bindings/leds/common.h>

    led-controller {
        compatible = "gpio-leds";

        led-0 {
            function = LED_FUNCTION_STATUS;
            linux,default-trigger = "heartbeat";
            gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
        };

        led-1 {
            function = LED_FUNCTION_USB;
            gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
            trigger-sources = <&ohci_port1>, <&ehci_port1>;
        };
    };

  - |
    #include <dt-bindings/leds/common.h>

    led-controller {
        compatible = "maxim,max77693-led";

        led {
            function = LED_FUNCTION_FLASH;
            color = <LED_COLOR_ID_WHITE>;
            led-sources = <0>, <1>;
            led-max-microamp = <50000>;
            flash-max-microamp = <320000>;
            flash-max-timeout-us = <500000>;
        };
    };

  - |
    #include <dt-bindings/leds/common.h>

    i2c {
        #address-cells = <1>;
        #size-cells = <0>;

        led-controller@30 {
            compatible = "panasonic,an30259a";
            reg = <0x30>;
            #address-cells = <1>;
            #size-cells = <0>;

            led@1 {
                reg = <1>;
                linux,default-trigger = "heartbeat";
                function = LED_FUNCTION_INDICATOR;
                function-enumerator = <1>;
            };

            led@2 {
                reg = <2>;
                function = LED_FUNCTION_INDICATOR;
                function-enumerator = <2>;
            };

            led@3 {
                reg = <3>;
                function = LED_FUNCTION_INDICATOR;
                function-enumerator = <3>;
            };
        };
    };

...
Commit	Line	Data
53633a89 TR	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: 14
	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 (see also "default-state" property)
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 disk read activity
93	- disk-read
94	# LED indicates disk write activity
95	- disk-write
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 indicates mic mute state
102	- audio-micmute
103	# LED indicates audio mute state
104	- audio-mute
105	# LED indicates bluetooth power state
106	- bluetooth-power
107	# LED indicates camera flash state
108	- flash
109	# LED indicated keyboard capslock
110	- kbd-capslock
111	# LED indicates MTD memory activity
112	- mtd
113	# LED indicates NAND memory activity (deprecated),
114	# in new implementations use "mtd"
115	- nand-disk
116	# No trigger assigned to the LED. This is the default mode
117	# if trigger is absent
118	- none
119	# LED indicates camera torch state
120	- torch
121	# LED indicates USB gadget activity
122	- usb-gadget
123	# LED indicates USB host activity
124	- usb-host
125	# LED indicates USB port state
126	- usbport
127	# LED is triggered by CPU activity
128	- pattern: "^cpu[0-9]*$"
129	# LED is triggered by Bluetooth activity
130	- pattern: "^hci[0-9]+-power$"
131	# LED is triggered by SD/MMC activity
132	- pattern: "^mmc[0-9]+$"
133	# LED is triggered by WLAN activity
134	- pattern: "^phy[0-9]+tx$"
135
136	led-pattern:
137	description: \|
138	Array of integers with default pattern for certain triggers.
139
140	Each trigger may parse this property differently:
141	- one-shot : two numbers specifying delay on and delay off (in ms),
142	- timer : two numbers specifying delay on and delay off (in ms),
143	- pattern : the pattern is given by a series of tuples, of
144	brightness and duration (in ms). The exact format is
145	described in:
146	Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt
147	$ref: /schemas/types.yaml#/definitions/uint32-matrix
148	items:
149	minItems: 2
150	maxItems: 2
151
152	led-max-microamp:
153	description:
154	Maximum LED supply current in microamperes. This property can be made
155	mandatory for the board configurations introducing a risk of hardware
156	damage in case an excessive current is set.
157	For flash LED controllers with configurable current this property is
158	mandatory for the LEDs in the non-flash modes (e.g. torch or indicator).
159
160	max-brightness:
161	description:
162	Normally, the maximum brightness is determined by the hardware, and this
163	property is not required. This property is used to set a software limit.
164	It could happen that an LED is made so bright that it gets damaged or
165	causes damage due to restrictions in a specific system, such as mounting
166	conditions.
167	Note that this flag is mainly used for PWM-LEDs, where it is not possible
168	to map brightness to current. Drivers for other controllers should use
169	led-max-microamp.
93743d24	170	$ref: /schemas/types.yaml#/definitions/uint32
53633a89 TR	171
	172	panic-indicator:
	173	description:
	174	This property specifies that the LED should be used, if at all possible,
	175	as a panic indicator.
	176	type: boolean
	177
	178	retain-state-shutdown:
	179	description:
	180	This property specifies that the LED should not be turned off or changed
	181	when the system shuts down.
	182	type: boolean
	183
	184	trigger-sources:
	185	description: \|
	186	List of devices which should be used as a source triggering this LED
	187	activity. Some LEDs can be related to a specific device and should somehow
	188	indicate its state. E.g. USB 2.0 LED may react to device(s) in a USB 2.0
	189	port(s).
	190	Another common example is switch or router with multiple Ethernet ports
	191	each of them having its own LED assigned (assuming they are not
	192	hardwired). In such cases this property should contain phandle(s) of
	193	related source device(s).
	194	Another example is a GPIO line that will be monitored and mirror the
	195	state of the line (with or without inversion flags) to the LED.
	196	In many cases LED can be related to more than one device (e.g. one USB LED
	197	vs. multiple USB ports). Each source should be represented by a node in
	198	the device tree and be referenced by a phandle and a set of phandle
	199	arguments. A length of arguments should be specified by the
	200	#trigger-source-cells property in the source node.
	201	$ref: /schemas/types.yaml#/definitions/phandle-array
	202
	203	# Required properties for flash LED child nodes:
	204	flash-max-microamp:
	205	description:
	206	Maximum flash LED supply current in microamperes. Required for flash LED
	207	nodes with configurable current.
	208
	209	flash-max-timeout-us:
	210	description:
	211	Maximum timeout in microseconds after which the flash LED is turned off.
	212	Required for flash LED nodes with configurable timeout.
	213
	214	additionalProperties: true
	215
	216	examples:
	217	- \|
	218	#include <dt-bindings/gpio/gpio.h>
	219	#include <dt-bindings/leds/common.h>
	220
	221	led-controller {
	222	compatible = "gpio-leds";
	223
	224	led-0 {
	225	function = LED_FUNCTION_STATUS;
	226	linux,default-trigger = "heartbeat";
	227	gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
	228	};
	229
	230	led-1 {
	231	function = LED_FUNCTION_USB;
	232	gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
	233	trigger-sources = <&ohci_port1>, <&ehci_port1>;
	234	};
235	};
236
237	- \|
238	#include <dt-bindings/leds/common.h>
239
240	led-controller {
241	compatible = "maxim,max77693-led";
242
243	led {
244	function = LED_FUNCTION_FLASH;
245	color = <LED_COLOR_ID_WHITE>;
246	led-sources = <0>, <1>;
247	led-max-microamp = <50000>;
248	flash-max-microamp = <320000>;
249	flash-max-timeout-us = <500000>;
250	};
251	};
252
253	- \|
254	#include <dt-bindings/leds/common.h>
255
256	i2c {
257	#address-cells = <1>;
258	#size-cells = <0>;
259
260	led-controller@30 {
261	compatible = "panasonic,an30259a";
262	reg = <0x30>;
263	#address-cells = <1>;
264	#size-cells = <0>;
265
266	led@1 {
267	reg = <1>;
268	linux,default-trigger = "heartbeat";
269	function = LED_FUNCTION_INDICATOR;
270	function-enumerator = <1>;
271	};
272
273	led@2 {
274	reg = <2>;
275	function = LED_FUNCTION_INDICATOR;
276	function-enumerator = <2>;
277	};
278
279	led@3 {
280	reg = <3>;
281	function = LED_FUNCTION_INDICATOR;
282	function-enumerator = <3>;
283	};
284	};
285	};
286
287	...