openkylin
/
linux
mirror of https://gitee.com/openkylin/linux.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity
linux/Documentation/leds/leds-class.rst

126 lines
5.0 KiB
ReStructuredText
Raw Normal View History

docs: leds: convert to ReST Rename the leds documentation files to ReST, add an index for them and adjust in order to produce a nice html output via the Sphinx build system. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Pavel Machek <pavel@ucw.cz> Signed-off-by: Jacek Anaszewski <jacek.anaszewski@gmail.com>
2019-06-28 20:20:20 +08:00
========================
[PATCH] LED: class documentation The LED class/subsystem takes John Lenz's work and extends and alters it to give what I think should be a fairly universal LED implementation. The series consists of several logical units: * LED Core + Class implementation * LED Trigger Core implementation * LED timer trigger (example of a complex trigger) * LED device drivers for corgi, spitz and tosa Zaurus models * LED device driver for locomo LEDs * LED device driver for ARM ixp4xx LEDs * Zaurus charging LED trigger * IDE disk activity LED trigger * NAND MTD activity LED trigger Why? ==== LEDs are really simple devices usually amounting to a GPIO that can be turned on and off so why do we need all this code? On handheld or embedded devices they're an important part of an often limited user interface. Both users and developers want to be able to control and configure what the LED does and the number of different things they'd potentially want the LED to show is large. A subsystem is needed to try and provide all this different functionality in an architecture independent, simple but complete, generic and scalable manner. The alternative is for everyone to implement just what they need hidden away in different corners of the kernel source tree and to provide an inconsistent interface to userspace. Other Implementations ===================== I'm aware of the existing arm led implementation. Currently the new subsystem and the arm code can coexist quite happily. Its up to the arm community to decide whether this new interface is acceptable to them. As far as I can see, the new interface can do everything the existing arm implementation can with the advantage that the new code is architecture independent and much more generic, configurable and scalable. I'm prepared to make the conversion to the LED subsystem (or assist with it) if appropriate. Implementation Details ====================== I've stripped a lot of code out of John's original LED class. Colours were removed as LED colour is now part of the device name. Multiple colours are to be handled as multiple led devices. This means you get full control over each colour. I also removed the LED hardware timer code as the generic timer isn't going to add much overhead and is just as useful. I also decided to have the LED core track the current LED status (to ease suspend/resume handling) removing the need for brightness_get implementations in the LED drivers. An underlying design philosophy is simplicity. The aim is to keep a small amount of code giving as much functionality as possible. The major new idea is the led "trigger". A trigger is a source of led events. Triggers can either be simple or complex. A simple trigger isn't configurable and is designed to slot into existing subsystems with minimal additional code. Examples are the ide-disk, nand-disk and zaurus-charging triggers. With leds disabled, the code optimises away. Examples are nand-disk and ide-disk. Complex triggers whilst available to all LEDs have LED specific parameters and work on a per LED basis. The timer trigger is an example. You can change triggers in a similar manner to the way an IO scheduler is chosen (via /sys/class/leds/somedevice/trigger). So far there are only a handful of examples but it should easy to add further LED triggers without too much interference into other subsystems. Known Issues ============ The LED Trigger core cannot be a module as the simple trigger functions would cause nightmare dependency issues. I see this as a minor issue compared to the benefits the simple trigger functionality brings. The rest of the LED subsystem can be modular. Some leds can be programmed to flash in hardware. As this isn't a generic LED device property, I think this should be exported as a device specific sysfs attribute rather than part of the class if this functionality is required (eg. to keep the led flashing whilst the device is suspended). Future Development ================== At the moment, a trigger can't be created specifically for a single LED. There are a number of cases where a trigger might only be mappable to a particular LED. The addition of triggers provided by the LED driver should cover this option and be possible to add without breaking the current interface. A CPU activity trigger similar to that found in the arm led implementation should be trivial to add. This patch: Add some brief documentation of the design decisions behind the LED class and how it appears to users. Signed-off-by: Richard Purdie <rpurdie@rpsys.net> Cc: Russell King <rmk@arm.linux.org.uk> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-03-31 18:31:03 +08:00
LED handling under Linux
========================
In its simplest form, the LED class just allows control of LEDs from
led: document sysfs interface Also fix Documentation/led-class.txt, the acceptable range of values for brightness is 0-max_brightness, not 0-255. Cc: Richard Purdie <rpurdie@rpsys.net> Signed-off-by: Corentin Chary <corentincj@iksaif.net> Signed-off-by: Len Brown <len.brown@intel.com>
2009-08-28 20:56:45 +08:00
userspace. LEDs appear in /sys/class/leds/. The maximum brightness of the
LED is defined in max_brightness file. The brightness file will set the brightness
of the LED (taking a value 0-max_brightness). Most LEDs don't have hardware
brightness support so will just be turned on for non-zero brightness settings.
[PATCH] LED: class documentation The LED class/subsystem takes John Lenz's work and extends and alters it to give what I think should be a fairly universal LED implementation. The series consists of several logical units: * LED Core + Class implementation * LED Trigger Core implementation * LED timer trigger (example of a complex trigger) * LED device drivers for corgi, spitz and tosa Zaurus models * LED device driver for locomo LEDs * LED device driver for ARM ixp4xx LEDs * Zaurus charging LED trigger * IDE disk activity LED trigger * NAND MTD activity LED trigger Why? ==== LEDs are really simple devices usually amounting to a GPIO that can be turned on and off so why do we need all this code? On handheld or embedded devices they're an important part of an often limited user interface. Both users and developers want to be able to control and configure what the LED does and the number of different things they'd potentially want the LED to show is large. A subsystem is needed to try and provide all this different functionality in an architecture independent, simple but complete, generic and scalable manner. The alternative is for everyone to implement just what they need hidden away in different corners of the kernel source tree and to provide an inconsistent interface to userspace. Other Implementations ===================== I'm aware of the existing arm led implementation. Currently the new subsystem and the arm code can coexist quite happily. Its up to the arm community to decide whether this new interface is acceptable to them. As far as I can see, the new interface can do everything the existing arm implementation can with the advantage that the new code is architecture independent and much more generic, configurable and scalable. I'm prepared to make the conversion to the LED subsystem (or assist with it) if appropriate. Implementation Details ====================== I've stripped a lot of code out of John's original LED class. Colours were removed as LED colour is now part of the device name. Multiple colours are to be handled as multiple led devices. This means you get full control over each colour. I also removed the LED hardware timer code as the generic timer isn't going to add much overhead and is just as useful. I also decided to have the LED core track the current LED status (to ease suspend/resume handling) removing the need for brightness_get implementations in the LED drivers. An underlying design philosophy is simplicity. The aim is to keep a small amount of code giving as much functionality as possible. The major new idea is the led "trigger". A trigger is a source of led events. Triggers can either be simple or complex. A simple trigger isn't configurable and is designed to slot into existing subsystems with minimal additional code. Examples are the ide-disk, nand-disk and zaurus-charging triggers. With leds disabled, the code optimises away. Examples are nand-disk and ide-disk. Complex triggers whilst available to all LEDs have LED specific parameters and work on a per LED basis. The timer trigger is an example. You can change triggers in a similar manner to the way an IO scheduler is chosen (via /sys/class/leds/somedevice/trigger). So far there are only a handful of examples but it should easy to add further LED triggers without too much interference into other subsystems. Known Issues ============ The LED Trigger core cannot be a module as the simple trigger functions would cause nightmare dependency issues. I see this as a minor issue compared to the benefits the simple trigger functionality brings. The rest of the LED subsystem can be modular. Some leds can be programmed to flash in hardware. As this isn't a generic LED device property, I think this should be exported as a device specific sysfs attribute rather than part of the class if this functionality is required (eg. to keep the led flashing whilst the device is suspended). Future Development ================== At the moment, a trigger can't be created specifically for a single LED. There are a number of cases where a trigger might only be mappable to a particular LED. The addition of triggers provided by the LED driver should cover this option and be possible to add without breaking the current interface. A CPU activity trigger similar to that found in the arm led implementation should be trivial to add. This patch: Add some brief documentation of the design decisions behind the LED class and how it appears to users. Signed-off-by: Richard Purdie <rpurdie@rpsys.net> Cc: Russell King <rmk@arm.linux.org.uk> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-03-31 18:31:03 +08:00
The class also introduces the optional concept of an LED trigger. A trigger
is a kernel based source of led events. Triggers can either be simple or
complex. A simple trigger isn't configurable and is designed to slot into
leds: documentation: 'ide-disk' to 'disk-activity' Signed-off-by: Stephan Linz <linz@li-pro.net> Cc: Joseph Jezak <josejx@gentoo.org> Cc: Jörg Sommer <joerg@alea.gnuu.de> Acked-by: Mark Rutland <mark.rutland@arm.com> Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com>
2016-06-25 01:16:53 +08:00
existing subsystems with minimal additional code. Examples are the disk-activity,
[PATCH] LED: class documentation The LED class/subsystem takes John Lenz's work and extends and alters it to give what I think should be a fairly universal LED implementation. The series consists of several logical units: * LED Core + Class implementation * LED Trigger Core implementation * LED timer trigger (example of a complex trigger) * LED device drivers for corgi, spitz and tosa Zaurus models * LED device driver for locomo LEDs * LED device driver for ARM ixp4xx LEDs * Zaurus charging LED trigger * IDE disk activity LED trigger * NAND MTD activity LED trigger Why? ==== LEDs are really simple devices usually amounting to a GPIO that can be turned on and off so why do we need all this code? On handheld or embedded devices they're an important part of an often limited user interface. Both users and developers want to be able to control and configure what the LED does and the number of different things they'd potentially want the LED to show is large. A subsystem is needed to try and provide all this different functionality in an architecture independent, simple but complete, generic and scalable manner. The alternative is for everyone to implement just what they need hidden away in different corners of the kernel source tree and to provide an inconsistent interface to userspace. Other Implementations ===================== I'm aware of the existing arm led implementation. Currently the new subsystem and the arm code can coexist quite happily. Its up to the arm community to decide whether this new interface is acceptable to them. As far as I can see, the new interface can do everything the existing arm implementation can with the advantage that the new code is architecture independent and much more generic, configurable and scalable. I'm prepared to make the conversion to the LED subsystem (or assist with it) if appropriate. Implementation Details ====================== I've stripped a lot of code out of John's original LED class. Colours were removed as LED colour is now part of the device name. Multiple colours are to be handled as multiple led devices. This means you get full control over each colour. I also removed the LED hardware timer code as the generic timer isn't going to add much overhead and is just as useful. I also decided to have the LED core track the current LED status (to ease suspend/resume handling) removing the need for brightness_get implementations in the LED drivers. An underlying design philosophy is simplicity. The aim is to keep a small amount of code giving as much functionality as possible. The major new idea is the led "trigger". A trigger is a source of led events. Triggers can either be simple or complex. A simple trigger isn't configurable and is designed to slot into existing subsystems with minimal additional code. Examples are the ide-disk, nand-disk and zaurus-charging triggers. With leds disabled, the code optimises away. Examples are nand-disk and ide-disk. Complex triggers whilst available to all LEDs have LED specific parameters and work on a per LED basis. The timer trigger is an example. You can change triggers in a similar manner to the way an IO scheduler is chosen (via /sys/class/leds/somedevice/trigger). So far there are only a handful of examples but it should easy to add further LED triggers without too much interference into other subsystems. Known Issues ============ The LED Trigger core cannot be a module as the simple trigger functions would cause nightmare dependency issues. I see this as a minor issue compared to the benefits the simple trigger functionality brings. The rest of the LED subsystem can be modular. Some leds can be programmed to flash in hardware. As this isn't a generic LED device property, I think this should be exported as a device specific sysfs attribute rather than part of the class if this functionality is required (eg. to keep the led flashing whilst the device is suspended). Future Development ================== At the moment, a trigger can't be created specifically for a single LED. There are a number of cases where a trigger might only be mappable to a particular LED. The addition of triggers provided by the LED driver should cover this option and be possible to add without breaking the current interface. A CPU activity trigger similar to that found in the arm led implementation should be trivial to add. This patch: Add some brief documentation of the design decisions behind the LED class and how it appears to users. Signed-off-by: Richard Purdie <rpurdie@rpsys.net> Cc: Russell King <rmk@arm.linux.org.uk> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-03-31 18:31:03 +08:00
nand-disk and sharpsl-charge triggers. With led triggers disabled, the code
optimises away.
Documentation: Use "while" instead of "whilst" Whilst making an unrelated change to some Documentation, Linus sayeth: | Afaik, even in Britain, "whilst" is unusual and considered more | formal, and "while" is the common word. | | [...] | | Can we just admit that we work with computers, and we don't need to | use þe eald Englisc spelling of words that most of the world never | uses? dictionary.com refers to the word as "Chiefly British", which is probably an undesirable attribute for technical documentation. Replace all occurrences under Documentation/ with "while". Cc: David Howells <dhowells@redhat.com> Cc: Liam Girdwood <lgirdwood@gmail.com> Cc: Chris Wilson <chris@chris-wilson.co.uk> Cc: Michael Halcrow <mhalcrow@google.com> Cc: Jonathan Corbet <corbet@lwn.net> Reported-by: Linus Torvalds <torvalds@linux-foundation.org> Signed-off-by: Will Deacon <will.deacon@arm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-11-19 19:02:45 +08:00
Complex triggers while available to all LEDs have LED specific
[PATCH] LED: class documentation The LED class/subsystem takes John Lenz's work and extends and alters it to give what I think should be a fairly universal LED implementation. The series consists of several logical units: * LED Core + Class implementation * LED Trigger Core implementation * LED timer trigger (example of a complex trigger) * LED device drivers for corgi, spitz and tosa Zaurus models * LED device driver for locomo LEDs * LED device driver for ARM ixp4xx LEDs * Zaurus charging LED trigger * IDE disk activity LED trigger * NAND MTD activity LED trigger Why? ==== LEDs are really simple devices usually amounting to a GPIO that can be turned on and off so why do we need all this code? On handheld or embedded devices they're an important part of an often limited user interface. Both users and developers want to be able to control and configure what the LED does and the number of different things they'd potentially want the LED to show is large. A subsystem is needed to try and provide all this different functionality in an architecture independent, simple but complete, generic and scalable manner. The alternative is for everyone to implement just what they need hidden away in different corners of the kernel source tree and to provide an inconsistent interface to userspace. Other Implementations ===================== I'm aware of the existing arm led implementation. Currently the new subsystem and the arm code can coexist quite happily. Its up to the arm community to decide whether this new interface is acceptable to them. As far as I can see, the new interface can do everything the existing arm implementation can with the advantage that the new code is architecture independent and much more generic, configurable and scalable. I'm prepared to make the conversion to the LED subsystem (or assist with it) if appropriate. Implementation Details ====================== I've stripped a lot of code out of John's original LED class. Colours were removed as LED colour is now part of the device name. Multiple colours are to be handled as multiple led devices. This means you get full control over each colour. I also removed the LED hardware timer code as the generic timer isn't going to add much overhead and is just as useful. I also decided to have the LED core track the current LED status (to ease suspend/resume handling) removing the need for brightness_get implementations in the LED drivers. An underlying design philosophy is simplicity. The aim is to keep a small amount of code giving as much functionality as possible. The major new idea is the led "trigger". A trigger is a source of led events. Triggers can either be simple or complex. A simple trigger isn't configurable and is designed to slot into existing subsystems with minimal additional code. Examples are the ide-disk, nand-disk and zaurus-charging triggers. With leds disabled, the code optimises away. Examples are nand-disk and ide-disk. Complex triggers whilst available to all LEDs have LED specific parameters and work on a per LED basis. The timer trigger is an example. You can change triggers in a similar manner to the way an IO scheduler is chosen (via /sys/class/leds/somedevice/trigger). So far there are only a handful of examples but it should easy to add further LED triggers without too much interference into other subsystems. Known Issues ============ The LED Trigger core cannot be a module as the simple trigger functions would cause nightmare dependency issues. I see this as a minor issue compared to the benefits the simple trigger functionality brings. The rest of the LED subsystem can be modular. Some leds can be programmed to flash in hardware. As this isn't a generic LED device property, I think this should be exported as a device specific sysfs attribute rather than part of the class if this functionality is required (eg. to keep the led flashing whilst the device is suspended). Future Development ================== At the moment, a trigger can't be created specifically for a single LED. There are a number of cases where a trigger might only be mappable to a particular LED. The addition of triggers provided by the LED driver should cover this option and be possible to add without breaking the current interface. A CPU activity trigger similar to that found in the arm led implementation should be trivial to add. This patch: Add some brief documentation of the design decisions behind the LED class and how it appears to users. Signed-off-by: Richard Purdie <rpurdie@rpsys.net> Cc: Russell King <rmk@arm.linux.org.uk> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-03-31 18:31:03 +08:00
parameters and work on a per LED basis. The timer trigger is an example.
leds: disable triggers on brightness set Disable any active triggers when the brightness attribute is set to zero. Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br> Signed-off-by: Márton Németh <nm127@freemail.hu> Signed-off-by: Richard Purdie <rpurdie@rpsys.net>
2008-03-10 04:54:37 +08:00
The timer trigger will periodically change the LED brightness between
LED_OFF and the current brightness setting. The "on" and "off" time can
be specified via /sys/class/leds/<device>/delay_{on,off} in milliseconds.
You can change the brightness value of a LED independently of the timer
trigger. However, if you set the brightness value to LED_OFF it will
also disable the timer trigger.
[PATCH] LED: class documentation The LED class/subsystem takes John Lenz's work and extends and alters it to give what I think should be a fairly universal LED implementation. The series consists of several logical units: * LED Core + Class implementation * LED Trigger Core implementation * LED timer trigger (example of a complex trigger) * LED device drivers for corgi, spitz and tosa Zaurus models * LED device driver for locomo LEDs * LED device driver for ARM ixp4xx LEDs * Zaurus charging LED trigger * IDE disk activity LED trigger * NAND MTD activity LED trigger Why? ==== LEDs are really simple devices usually amounting to a GPIO that can be turned on and off so why do we need all this code? On handheld or embedded devices they're an important part of an often limited user interface. Both users and developers want to be able to control and configure what the LED does and the number of different things they'd potentially want the LED to show is large. A subsystem is needed to try and provide all this different functionality in an architecture independent, simple but complete, generic and scalable manner. The alternative is for everyone to implement just what they need hidden away in different corners of the kernel source tree and to provide an inconsistent interface to userspace. Other Implementations ===================== I'm aware of the existing arm led implementation. Currently the new subsystem and the arm code can coexist quite happily. Its up to the arm community to decide whether this new interface is acceptable to them. As far as I can see, the new interface can do everything the existing arm implementation can with the advantage that the new code is architecture independent and much more generic, configurable and scalable. I'm prepared to make the conversion to the LED subsystem (or assist with it) if appropriate. Implementation Details ====================== I've stripped a lot of code out of John's original LED class. Colours were removed as LED colour is now part of the device name. Multiple colours are to be handled as multiple led devices. This means you get full control over each colour. I also removed the LED hardware timer code as the generic timer isn't going to add much overhead and is just as useful. I also decided to have the LED core track the current LED status (to ease suspend/resume handling) removing the need for brightness_get implementations in the LED drivers. An underlying design philosophy is simplicity. The aim is to keep a small amount of code giving as much functionality as possible. The major new idea is the led "trigger". A trigger is a source of led events. Triggers can either be simple or complex. A simple trigger isn't configurable and is designed to slot into existing subsystems with minimal additional code. Examples are the ide-disk, nand-disk and zaurus-charging triggers. With leds disabled, the code optimises away. Examples are nand-disk and ide-disk. Complex triggers whilst available to all LEDs have LED specific parameters and work on a per LED basis. The timer trigger is an example. You can change triggers in a similar manner to the way an IO scheduler is chosen (via /sys/class/leds/somedevice/trigger). So far there are only a handful of examples but it should easy to add further LED triggers without too much interference into other subsystems. Known Issues ============ The LED Trigger core cannot be a module as the simple trigger functions would cause nightmare dependency issues. I see this as a minor issue compared to the benefits the simple trigger functionality brings. The rest of the LED subsystem can be modular. Some leds can be programmed to flash in hardware. As this isn't a generic LED device property, I think this should be exported as a device specific sysfs attribute rather than part of the class if this functionality is required (eg. to keep the led flashing whilst the device is suspended). Future Development ================== At the moment, a trigger can't be created specifically for a single LED. There are a number of cases where a trigger might only be mappable to a particular LED. The addition of triggers provided by the LED driver should cover this option and be possible to add without breaking the current interface. A CPU activity trigger similar to that found in the arm led implementation should be trivial to add. This patch: Add some brief documentation of the design decisions behind the LED class and how it appears to users. Signed-off-by: Richard Purdie <rpurdie@rpsys.net> Cc: Russell King <rmk@arm.linux.org.uk> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-03-31 18:31:03 +08:00
You can change triggers in a similar manner to the way an IO scheduler
is chosen (via /sys/class/leds/<device>/trigger). Trigger specific
parameters can appear in /sys/class/leds/<device> once a given trigger is
selected.
Design Philosophy
=================
The underlying design philosophy is simplicity. LEDs are simple devices
and the aim is to keep a small amount of code giving as much functionality
as possible. Please keep this in mind when suggesting enhancements.
LED Device Naming
=================
Is currently of the form:
docs: leds: convert to ReST Rename the leds documentation files to ReST, add an index for them and adjust in order to produce a nice html output via the Sphinx build system. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Pavel Machek <pavel@ucw.cz> Signed-off-by: Jacek Anaszewski <jacek.anaszewski@gmail.com>
2019-06-28 20:20:20 +08:00
"devicename:colour:function"
[PATCH] LED: class documentation The LED class/subsystem takes John Lenz's work and extends and alters it to give what I think should be a fairly universal LED implementation. The series consists of several logical units: * LED Core + Class implementation * LED Trigger Core implementation * LED timer trigger (example of a complex trigger) * LED device drivers for corgi, spitz and tosa Zaurus models * LED device driver for locomo LEDs * LED device driver for ARM ixp4xx LEDs * Zaurus charging LED trigger * IDE disk activity LED trigger * NAND MTD activity LED trigger Why? ==== LEDs are really simple devices usually amounting to a GPIO that can be turned on and off so why do we need all this code? On handheld or embedded devices they're an important part of an often limited user interface. Both users and developers want to be able to control and configure what the LED does and the number of different things they'd potentially want the LED to show is large. A subsystem is needed to try and provide all this different functionality in an architecture independent, simple but complete, generic and scalable manner. The alternative is for everyone to implement just what they need hidden away in different corners of the kernel source tree and to provide an inconsistent interface to userspace. Other Implementations ===================== I'm aware of the existing arm led implementation. Currently the new subsystem and the arm code can coexist quite happily. Its up to the arm community to decide whether this new interface is acceptable to them. As far as I can see, the new interface can do everything the existing arm implementation can with the advantage that the new code is architecture independent and much more generic, configurable and scalable. I'm prepared to make the conversion to the LED subsystem (or assist with it) if appropriate. Implementation Details ====================== I've stripped a lot of code out of John's original LED class. Colours were removed as LED colour is now part of the device name. Multiple colours are to be handled as multiple led devices. This means you get full control over each colour. I also removed the LED hardware timer code as the generic timer isn't going to add much overhead and is just as useful. I also decided to have the LED core track the current LED status (to ease suspend/resume handling) removing the need for brightness_get implementations in the LED drivers. An underlying design philosophy is simplicity. The aim is to keep a small amount of code giving as much functionality as possible. The major new idea is the led "trigger". A trigger is a source of led events. Triggers can either be simple or complex. A simple trigger isn't configurable and is designed to slot into existing subsystems with minimal additional code. Examples are the ide-disk, nand-disk and zaurus-charging triggers. With leds disabled, the code optimises away. Examples are nand-disk and ide-disk. Complex triggers whilst available to all LEDs have LED specific parameters and work on a per LED basis. The timer trigger is an example. You can change triggers in a similar manner to the way an IO scheduler is chosen (via /sys/class/leds/somedevice/trigger). So far there are only a handful of examples but it should easy to add further LED triggers without too much interference into other subsystems. Known Issues ============ The LED Trigger core cannot be a module as the simple trigger functions would cause nightmare dependency issues. I see this as a minor issue compared to the benefits the simple trigger functionality brings. The rest of the LED subsystem can be modular. Some leds can be programmed to flash in hardware. As this isn't a generic LED device property, I think this should be exported as a device specific sysfs attribute rather than part of the class if this functionality is required (eg. to keep the led flashing whilst the device is suspended). Future Development ================== At the moment, a trigger can't be created specifically for a single LED. There are a number of cases where a trigger might only be mappable to a particular LED. The addition of triggers provided by the LED driver should cover this option and be possible to add without breaking the current interface. A CPU activity trigger similar to that found in the arm led implementation should be trivial to add. This patch: Add some brief documentation of the design decisions behind the LED class and how it appears to users. Signed-off-by: Richard Purdie <rpurdie@rpsys.net> Cc: Russell King <rmk@arm.linux.org.uk> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-03-31 18:31:03 +08:00
There have been calls for LED properties such as colour to be exported as
individual led class attributes. As a solution which doesn't incur as much
overhead, I suggest these become part of the device name. The naming scheme
leds: Standardise LED naming scheme As discussed on LKML some notion of 'function' is needed in LED naming. This patch adds this to the documentation and standardises existing LED drivers. Signed-off-by: Richard Purdie <rpurdie@rpsys.net>
2007-10-31 22:00:07 +08:00
above leaves scope for further attributes should they be needed. If sections
of the name don't apply, just leave that section blank.
[PATCH] LED: class documentation The LED class/subsystem takes John Lenz's work and extends and alters it to give what I think should be a fairly universal LED implementation. The series consists of several logical units: * LED Core + Class implementation * LED Trigger Core implementation * LED timer trigger (example of a complex trigger) * LED device drivers for corgi, spitz and tosa Zaurus models * LED device driver for locomo LEDs * LED device driver for ARM ixp4xx LEDs * Zaurus charging LED trigger * IDE disk activity LED trigger * NAND MTD activity LED trigger Why? ==== LEDs are really simple devices usually amounting to a GPIO that can be turned on and off so why do we need all this code? On handheld or embedded devices they're an important part of an often limited user interface. Both users and developers want to be able to control and configure what the LED does and the number of different things they'd potentially want the LED to show is large. A subsystem is needed to try and provide all this different functionality in an architecture independent, simple but complete, generic and scalable manner. The alternative is for everyone to implement just what they need hidden away in different corners of the kernel source tree and to provide an inconsistent interface to userspace. Other Implementations ===================== I'm aware of the existing arm led implementation. Currently the new subsystem and the arm code can coexist quite happily. Its up to the arm community to decide whether this new interface is acceptable to them. As far as I can see, the new interface can do everything the existing arm implementation can with the advantage that the new code is architecture independent and much more generic, configurable and scalable. I'm prepared to make the conversion to the LED subsystem (or assist with it) if appropriate. Implementation Details ====================== I've stripped a lot of code out of John's original LED class. Colours were removed as LED colour is now part of the device name. Multiple colours are to be handled as multiple led devices. This means you get full control over each colour. I also removed the LED hardware timer code as the generic timer isn't going to add much overhead and is just as useful. I also decided to have the LED core track the current LED status (to ease suspend/resume handling) removing the need for brightness_get implementations in the LED drivers. An underlying design philosophy is simplicity. The aim is to keep a small amount of code giving as much functionality as possible. The major new idea is the led "trigger". A trigger is a source of led events. Triggers can either be simple or complex. A simple trigger isn't configurable and is designed to slot into existing subsystems with minimal additional code. Examples are the ide-disk, nand-disk and zaurus-charging triggers. With leds disabled, the code optimises away. Examples are nand-disk and ide-disk. Complex triggers whilst available to all LEDs have LED specific parameters and work on a per LED basis. The timer trigger is an example. You can change triggers in a similar manner to the way an IO scheduler is chosen (via /sys/class/leds/somedevice/trigger). So far there are only a handful of examples but it should easy to add further LED triggers without too much interference into other subsystems. Known Issues ============ The LED Trigger core cannot be a module as the simple trigger functions would cause nightmare dependency issues. I see this as a minor issue compared to the benefits the simple trigger functionality brings. The rest of the LED subsystem can be modular. Some leds can be programmed to flash in hardware. As this isn't a generic LED device property, I think this should be exported as a device specific sysfs attribute rather than part of the class if this functionality is required (eg. to keep the led flashing whilst the device is suspended). Future Development ================== At the moment, a trigger can't be created specifically for a single LED. There are a number of cases where a trigger might only be mappable to a particular LED. The addition of triggers provided by the LED driver should cover this option and be possible to add without breaking the current interface. A CPU activity trigger similar to that found in the arm led implementation should be trivial to add. This patch: Add some brief documentation of the design decisions behind the LED class and how it appears to users. Signed-off-by: Richard Purdie <rpurdie@rpsys.net> Cc: Russell King <rmk@arm.linux.org.uk> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-03-31 18:31:03 +08:00
Documentation: leds: Add description of brightness setting API This patch adds description of the LED subsystem API for setting an LED brightness. Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com> Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
2015-10-07 17:10:44 +08:00
Brightness setting API
======================
LED subsystem core exposes following API for setting brightness:
docs: leds: convert to ReST Rename the leds documentation files to ReST, add an index for them and adjust in order to produce a nice html output via the Sphinx build system. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Pavel Machek <pavel@ucw.cz> Signed-off-by: Jacek Anaszewski <jacek.anaszewski@gmail.com>
2019-06-28 20:20:20 +08:00
- led_set_brightness:
it is guaranteed not to sleep, passing LED_OFF stops
Documentation: leds: Add description of brightness setting API This patch adds description of the LED subsystem API for setting an LED brightness. Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com> Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
2015-10-07 17:10:44 +08:00
blinking,
docs: leds: convert to ReST Rename the leds documentation files to ReST, add an index for them and adjust in order to produce a nice html output via the Sphinx build system. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Pavel Machek <pavel@ucw.cz> Signed-off-by: Jacek Anaszewski <jacek.anaszewski@gmail.com>
2019-06-28 20:20:20 +08:00
- led_set_brightness_sync:
for use cases when immediate effect is desired -
Documentation: leds: Add description of brightness setting API This patch adds description of the LED subsystem API for setting an LED brightness. Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com> Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
2015-10-07 17:10:44 +08:00
it can block the caller for the time required for accessing
device registers and can sleep, passing LED_OFF stops hardware
blinking, returns -EBUSY if software blink fallback is enabled.
leds: class: Add new optional brightness_hw_changed attribute Some LEDs may have their brightness level changed autonomously (outside of kernel control) by hardware / firmware. This commit adds support for an optional brightness_hw_changed attribute to signal such changes to userspace (if a driver can detect them): What: /sys/class/leds/<led>/brightness_hw_changed Date: January 2017 KernelVersion: 4.11 Description: Last hardware set brightness level for this LED. Some LEDs may be changed autonomously by hardware/firmware. Only LEDs where this happens and the driver can detect this, will have this file. This file supports poll() to detect when the hardware changes the brightness. Reading this file will return the last brightness level set by the hardware, this may be different from the current brightness. Drivers which want to support this, simply add LED_BRIGHT_HW_CHANGED to their flags field and call led_classdev_notify_brightness_hw_changed() with the hardware set brightness when they detect a hardware / firmware triggered brightness change. Signed-off-by: Hans de Goede <hdegoede@redhat.com> Acked-by: Pavel Machek <pavel@ucw.cz> Signed-off-by: Jacek Anaszewski <jacek.anaszewski@gmail.com>
2017-01-29 21:42:52 +08:00
LED registration API
====================
A driver wanting to register a LED classdev for use by other drivers /
userspace needs to allocate and fill a led_classdev struct and then call
docs: leds: convert to ReST Rename the leds documentation files to ReST, add an index for them and adjust in order to produce a nice html output via the Sphinx build system. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Pavel Machek <pavel@ucw.cz> Signed-off-by: Jacek Anaszewski <jacek.anaszewski@gmail.com>
2019-06-28 20:20:20 +08:00
`[devm_]led_classdev_register`. If the non devm version is used the driver
leds: class: Add new optional brightness_hw_changed attribute Some LEDs may have their brightness level changed autonomously (outside of kernel control) by hardware / firmware. This commit adds support for an optional brightness_hw_changed attribute to signal such changes to userspace (if a driver can detect them): What: /sys/class/leds/<led>/brightness_hw_changed Date: January 2017 KernelVersion: 4.11 Description: Last hardware set brightness level for this LED. Some LEDs may be changed autonomously by hardware/firmware. Only LEDs where this happens and the driver can detect this, will have this file. This file supports poll() to detect when the hardware changes the brightness. Reading this file will return the last brightness level set by the hardware, this may be different from the current brightness. Drivers which want to support this, simply add LED_BRIGHT_HW_CHANGED to their flags field and call led_classdev_notify_brightness_hw_changed() with the hardware set brightness when they detect a hardware / firmware triggered brightness change. Signed-off-by: Hans de Goede <hdegoede@redhat.com> Acked-by: Pavel Machek <pavel@ucw.cz> Signed-off-by: Jacek Anaszewski <jacek.anaszewski@gmail.com>
2017-01-29 21:42:52 +08:00
must call led_classdev_unregister from its remove function before
free-ing the led_classdev struct.
If the driver can detect hardware initiated brightness changes and thus
wants to have a brightness_hw_changed attribute then the LED_BRIGHT_HW_CHANGED
flag must be set in flags before registering. Calling
led_classdev_notify_brightness_hw_changed on a classdev not registered with
the LED_BRIGHT_HW_CHANGED flag is a bug and will trigger a WARN_ON.
leds: Add support for hardware accelerated LED flashing Extends the leds subsystem with a blink_set() callback function which can be optionally implemented by a LED driver. If implemented, the driver can use the hardware acceleration for blinking a LED. Signed-off-by: Márton Németh <nm127@freemail.hu> Signed-off-by: Richard Purdie <rpurdie@rpsys.net>
2007-10-31 22:07:12 +08:00
Hardware accelerated blink of LEDs
==================================
Some LEDs can be programmed to blink without any CPU interaction. To
support this feature, a LED driver can optionally implement the
led-class: always implement blinking Currently, blinking LEDs can be awkward because it is not guaranteed that all LEDs implement blinking. The trigger that wants it to blink then needs to implement its own timer solution. Rather than require that, add led_blink_set() API that triggers can use. This function will attempt to use hw blinking, but if that fails implements a timer for it. To stop blinking again, brightness_set() also needs to be wrapped into API that will stop the software blink. As a result of this, the timer trigger becomes a very trivial one, and hopefully we can finally see triggers using blinking as well because it's always easy to use. Signed-off-by: Johannes Berg <johannes.berg@intel.com> Acked-by: Richard Purdie <rpurdie@linux.intel.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-11-12 06:05:21 +08:00
blink_set() function (see <linux/leds.h>). To set an LED to blinking,
Documentation: fix leds-class.txt duplicated word Fix a typo (duplicated word) in Documentation/leds/leds-class.txt Signed-off-by: Bryan Wu <bryan.wu@canonical.com> Acked-by: Richard Purdie <rchard.purdie@linuxfoundation.org> Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2011-11-05 02:22:29 +08:00
however, it is better to use the API function led_blink_set(), as it
will check and implement software fallback if necessary.
led-class: always implement blinking Currently, blinking LEDs can be awkward because it is not guaranteed that all LEDs implement blinking. The trigger that wants it to blink then needs to implement its own timer solution. Rather than require that, add led_blink_set() API that triggers can use. This function will attempt to use hw blinking, but if that fails implements a timer for it. To stop blinking again, brightness_set() also needs to be wrapped into API that will stop the software blink. As a result of this, the timer trigger becomes a very trivial one, and hopefully we can finally see triggers using blinking as well because it's always easy to use. Signed-off-by: Johannes Berg <johannes.berg@intel.com> Acked-by: Richard Purdie <rpurdie@linux.intel.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-11-12 06:05:21 +08:00
leds: core: Fix brightness setting upon hardware blinking enabled Commit 76931edd54f8 ("leds: fix brightness changing when software blinking is active") changed the semantics of led_set_brightness() which according to the documentation should disable blinking upon any brightness setting. Moreover it made it different for soft blink case, where it was possible to change blink brightness, and for hardware blink case, where setting any brightness greater than 0 was ignored. While the change itself is against the documentation claims, it was driven also by the fact that timer trigger remained active after turning blinking off. Fixing that would have required major refactoring in the led-core, led-class, and led-triggers because of cyclic dependencies. Finally, it has been decided that allowing for brightness change during blinking is beneficial as it can be accomplished without disturbing blink rhythm. The change in brightness setting semantics will not affect existing LED class drivers that implement blink_set op thanks to the LED_BLINK_SW flag introduced by this patch. The flag state will be from now on checked in led_set_brightness() which will allow to distinguish between software and hardware blink mode. In the latter case the control will be passed directly to the drivers which apply their semantics on brightness set, which is disable the blinking in case of most such drivers. New drivers will apply new semantics and just change the brightness while hardware blinking is on, if possible. The issue was smuggled by subsequent LED core improvements, which modified the code that originally introduced the problem. Fixes: f1e80c07416a ("leds: core: Add two new LED_BLINK_ flags") Signed-off-by: Tony Makkiel <tony.makkiel@daqri.com> Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com>
2016-05-19 00:22:45 +08:00
To turn off blinking, use the API function led_brightness_set()
with brightness value LED_OFF, which should stop any software
led-class: always implement blinking Currently, blinking LEDs can be awkward because it is not guaranteed that all LEDs implement blinking. The trigger that wants it to blink then needs to implement its own timer solution. Rather than require that, add led_blink_set() API that triggers can use. This function will attempt to use hw blinking, but if that fails implements a timer for it. To stop blinking again, brightness_set() also needs to be wrapped into API that will stop the software blink. As a result of this, the timer trigger becomes a very trivial one, and hopefully we can finally see triggers using blinking as well because it's always easy to use. Signed-off-by: Johannes Berg <johannes.berg@intel.com> Acked-by: Richard Purdie <rpurdie@linux.intel.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-11-12 06:05:21 +08:00
timers that may have been required for blinking.
The blink_set() function should choose a user friendly blinking value
docs: leds: convert to ReST Rename the leds documentation files to ReST, add an index for them and adjust in order to produce a nice html output via the Sphinx build system. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Pavel Machek <pavel@ucw.cz> Signed-off-by: Jacek Anaszewski <jacek.anaszewski@gmail.com>
2019-06-28 20:20:20 +08:00
if it is called with `*delay_on==0` && `*delay_off==0` parameters. In this
led-class: always implement blinking Currently, blinking LEDs can be awkward because it is not guaranteed that all LEDs implement blinking. The trigger that wants it to blink then needs to implement its own timer solution. Rather than require that, add led_blink_set() API that triggers can use. This function will attempt to use hw blinking, but if that fails implements a timer for it. To stop blinking again, brightness_set() also needs to be wrapped into API that will stop the software blink. As a result of this, the timer trigger becomes a very trivial one, and hopefully we can finally see triggers using blinking as well because it's always easy to use. Signed-off-by: Johannes Berg <johannes.berg@intel.com> Acked-by: Richard Purdie <rpurdie@linux.intel.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-11-12 06:05:21 +08:00
case the driver should give back the chosen value through delay_on and
delay_off parameters to the leds subsystem.
leds: Add support for hardware accelerated LED flashing Extends the leds subsystem with a blink_set() callback function which can be optionally implemented by a LED driver. If implemented, the driver can use the hardware acceleration for blinking a LED. Signed-off-by: Márton Németh <nm127@freemail.hu> Signed-off-by: Richard Purdie <rpurdie@rpsys.net>
2007-10-31 22:07:12 +08:00
leds: disable triggers on brightness set Disable any active triggers when the brightness attribute is set to zero. Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br> Signed-off-by: Márton Németh <nm127@freemail.hu> Signed-off-by: Richard Purdie <rpurdie@rpsys.net>
2008-03-10 04:54:37 +08:00
Setting the brightness to zero with brightness_set() callback function
should completely turn off the LED and cancel the previously programmed
hardware blinking function, if any.
leds: Add support for hardware accelerated LED flashing Extends the leds subsystem with a blink_set() callback function which can be optionally implemented by a LED driver. If implemented, the driver can use the hardware acceleration for blinking a LED. Signed-off-by: Márton Németh <nm127@freemail.hu> Signed-off-by: Richard Purdie <rpurdie@rpsys.net>
2007-10-31 22:07:12 +08:00
[PATCH] LED: class documentation The LED class/subsystem takes John Lenz's work and extends and alters it to give what I think should be a fairly universal LED implementation. The series consists of several logical units: * LED Core + Class implementation * LED Trigger Core implementation * LED timer trigger (example of a complex trigger) * LED device drivers for corgi, spitz and tosa Zaurus models * LED device driver for locomo LEDs * LED device driver for ARM ixp4xx LEDs * Zaurus charging LED trigger * IDE disk activity LED trigger * NAND MTD activity LED trigger Why? ==== LEDs are really simple devices usually amounting to a GPIO that can be turned on and off so why do we need all this code? On handheld or embedded devices they're an important part of an often limited user interface. Both users and developers want to be able to control and configure what the LED does and the number of different things they'd potentially want the LED to show is large. A subsystem is needed to try and provide all this different functionality in an architecture independent, simple but complete, generic and scalable manner. The alternative is for everyone to implement just what they need hidden away in different corners of the kernel source tree and to provide an inconsistent interface to userspace. Other Implementations ===================== I'm aware of the existing arm led implementation. Currently the new subsystem and the arm code can coexist quite happily. Its up to the arm community to decide whether this new interface is acceptable to them. As far as I can see, the new interface can do everything the existing arm implementation can with the advantage that the new code is architecture independent and much more generic, configurable and scalable. I'm prepared to make the conversion to the LED subsystem (or assist with it) if appropriate. Implementation Details ====================== I've stripped a lot of code out of John's original LED class. Colours were removed as LED colour is now part of the device name. Multiple colours are to be handled as multiple led devices. This means you get full control over each colour. I also removed the LED hardware timer code as the generic timer isn't going to add much overhead and is just as useful. I also decided to have the LED core track the current LED status (to ease suspend/resume handling) removing the need for brightness_get implementations in the LED drivers. An underlying design philosophy is simplicity. The aim is to keep a small amount of code giving as much functionality as possible. The major new idea is the led "trigger". A trigger is a source of led events. Triggers can either be simple or complex. A simple trigger isn't configurable and is designed to slot into existing subsystems with minimal additional code. Examples are the ide-disk, nand-disk and zaurus-charging triggers. With leds disabled, the code optimises away. Examples are nand-disk and ide-disk. Complex triggers whilst available to all LEDs have LED specific parameters and work on a per LED basis. The timer trigger is an example. You can change triggers in a similar manner to the way an IO scheduler is chosen (via /sys/class/leds/somedevice/trigger). So far there are only a handful of examples but it should easy to add further LED triggers without too much interference into other subsystems. Known Issues ============ The LED Trigger core cannot be a module as the simple trigger functions would cause nightmare dependency issues. I see this as a minor issue compared to the benefits the simple trigger functionality brings. The rest of the LED subsystem can be modular. Some leds can be programmed to flash in hardware. As this isn't a generic LED device property, I think this should be exported as a device specific sysfs attribute rather than part of the class if this functionality is required (eg. to keep the led flashing whilst the device is suspended). Future Development ================== At the moment, a trigger can't be created specifically for a single LED. There are a number of cases where a trigger might only be mappable to a particular LED. The addition of triggers provided by the LED driver should cover this option and be possible to add without breaking the current interface. A CPU activity trigger similar to that found in the arm led implementation should be trivial to add. This patch: Add some brief documentation of the design decisions behind the LED class and how it appears to users. Signed-off-by: Richard Purdie <rpurdie@rpsys.net> Cc: Russell King <rmk@arm.linux.org.uk> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-03-31 18:31:03 +08:00
Known Issues
============
The LED Trigger core cannot be a module as the simple trigger functions
would cause nightmare dependency issues. I see this as a minor issue
compared to the benefits the simple trigger functionality brings. The
rest of the LED subsystem can be modular.
Future Development
==================
At the moment, a trigger can't be created specifically for a single LED.
There are a number of cases where a trigger might only be mappable to a
particular LED (ACPI?). The addition of triggers provided by the LED driver
should cover this option and be possible to add without breaking the
current interface.