Commit 76931edd ("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: f1e80c07 ("leds: core: Add two new LED_BLINK_ flags")
Signed-off-by: NTony Makkiel <tony.makkiel@daqri.com>
Signed-off-by: NJacek Anaszewski <j.anaszewski@samsung.com>

This patch adds description of the LED subsystem API for
setting an LED brightness.
Signed-off-by: NJacek Anaszewski <j.anaszewski@samsung.com>
Acked-by: NSakari Ailus <sakari.ailus@linux.intel.com>

This change creates a new input handler called "leds" that exports LEDs on input
devices as standard LED class devices in sysfs and allows controlling their
state via sysfs or via any of the standard LED triggers. This allows to
re-purpose and reassign LDEs on the keyboards to represent states other
than the standard keyboard states (CapsLock, NumLock, etc).

The old API of controlling input LEDs by writing into /dev/input/eventX
devices is still present and will take precedence over accessing via LEDs
subsystem (i.e. it may override state set by a trigger). If input device is
"grabbed" then requests coming through LED subsystem will be ignored.
Signed-off-by: NSamuel Thibault <samuel.thibault@ens-lyon.org>
Tested-by: NPavel Machek <pavel@ucw.cz>
Acked-by: NPavel Machek <pavel@ucw.cz>
Signed-off-by: NDmitry Torokhov <dmitry.torokhov@gmail.com>

Fix a typo (duplicated word) in Documentation/leds/leds-class.txt
Signed-off-by: NBryan Wu <bryan.wu@canonical.com>
Acked-by: NRichard Purdie <rchard.purdie@linuxfoundation.org>
Signed-off-by: NRandy Dunlap <rdunlap@xenotime.net>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

leds: move leds-class documentation under the leds/ subdir.
Add also a leds/00-INDEX file describing the files under leds/
Signed-off-by: NAntonio Ospite <ospite@studenti.unina.it>
Acked-by: NRichard Purdie <richard.purdie@linuxfoundation.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

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: NJohannes Berg <johannes.berg@intel.com>
Acked-by: NRichard Purdie <rpurdie@linux.intel.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

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: NCorentin Chary <corentincj@iksaif.net>
Signed-off-by: NLen Brown <len.brown@intel.com>

Cc: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Disable any active triggers when the brightness attribute is
set to zero.
Signed-off-by: NHenrique de Moraes Holschuh <hmh@hmh.eng.br>
Signed-off-by: NMárton Németh <nm127@freemail.hu>
Signed-off-by: NRichard Purdie <rpurdie@rpsys.net>

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: NMárton Németh <nm127@freemail.hu>
Signed-off-by: NRichard Purdie <rpurdie@rpsys.net>

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: NRichard Purdie <rpurdie@rpsys.net>

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: NRichard Purdie <rpurdie@rpsys.net>
Cc: Russell King <rmk@arm.linux.org.uk>
Signed-off-by: NAndrew Morton <akpm@osdl.org>
Signed-off-by: NLinus Torvalds <torvalds@osdl.org>