[PATCH/RFC v2 3/8] Documentation: leds: Add description of flash mode

[Jacek Anaszewski <j.anaszewski@samsung.com>]

Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com>
Acked-by: Kyungmin Park <kyungmin.park@samsung.com>
Cc: Bryan Wu <cooloney@gmail.com>
Cc: Richard Purdie <rpurdie@rpsys.net>
---
 Documentation/leds/leds-class.txt |   52 +++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/Documentation/leds/leds-class.txt b/Documentation/leds/leds-class.txt
index 62261c0..ea50d27 100644
--- a/Documentation/leds/leds-class.txt
+++ b/Documentation/leds/leds-class.txt
@@ -8,6 +8,58 @@ LED is defined in max_brightness file. The brightness file will set the brightne
 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.
 
+Some LED devices support two modes - torch and flash. In order to enable
+support for flash LEDs the CONFIG_LEDS_CLASS_FLASH symbol must be defined
+in the kernel config. A flash LED driver must initialize the "flash" field
+of the led_classdev structure (see <linux/leds_flash.h>) to enable flash
+related features of the LED subsystem for the driver.
+
+There are seven sysfs attributes dedicated specifically to the flash LED devices:
+
+	- flash_brightness - flash LED brightness in milliampers (RW)
+	- max_flash_brightness - maximum available flash LED brightness (RO)
+	- flash_timeout - flash strobe duration in milliseconds (RW)
+	- max_flash_timeout - maximum available flash strobe duration (RO)
+	- flash_strobe - flash strobe state (RW)
+	- flash_fault - bitmask of flash faults that may have occured, possible
+			flags are:
+		* 0x01 - flash controller voltage to the flash LED has exceeded
+			 the limit specific to the flash controller
+		* 0x02 - the flash strobe was still on when the timeout set by
+			 the user has expired; not all flash controllers may set
+			 this in all such conditions
+		* 0x04 - the flash controller has overheated
+		* 0x08 - the short circuit protection of the flash controller
+			 has been triggered
+		* 0x10 - current in the LED power supply has exceeded the limit
+			 specific to the flash controller
+		* 0x40 - flash controller voltage to the flash LED has been below
+			 the minimum limit specific to the flash
+		* 0x80 - the input voltage of the flash controller is below
+			 the limit under which strobing the flash at full current
+			 will not be possible. The condition persists until this
+			 flag is no longer set
+		* 0x100 - the temperature of the LED has exceeded its allowed
+			  upper limit
+	- hw_triggered - some devices expose dedicated hardware pins for
+			 triggering a flash LED - the attribute allows to set
+			 this mode (RW)
+
+The LED subsystem driver can be controlled also from the level of
+the VideoForLinux2 subsystem. In order to enable this the CONFIG_V4L2_FLASH
+symbol has to be defined in the kernel config. The driver must
+initialize v4l2_flash_ctrl_config structure and pass it to the v4l2_flash_init
+function. On remove v4l2_flash_release has to be called (see <media/v4l2-flash.h>).
+After proper initialization V4L2 Flash sub-device is created. The sub-device
+must be registered by a V4L2 video device to become available for the user
+space. This is accomplished with use of asynchronous sub-device registration
+mechanism (see <media/v4l2-async.h>).
+A V4l2 Flash sub-device exposes a number of V4L2 controls.
+When the V4L2_CID_FLASH_LED_MODE control is set to V4L2_FLASH_LED_MODE_TORCH
+or V4L2_FLASH_LED_MODE_FLASH the LED subsystem sysfs interface becomes
+unavailable. The interface can be unlocked by setting the mode back
+to V4L2_FLASH_LED_MODE_NONE.
+
 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
-- 
1.7.9.5