docs: leds: convert to ReST

sysfs notes:

The ThinkLight sysfs interface is documented by the LED class

documentation, in Documentation/leds/leds-class.txt.  The ThinkLight LED name

documentation, in Documentation/leds/leds-class.rst.  The ThinkLight LED name

is "tpacpi::thinklight".

Due to limitations in the sysfs LED class, if the status of the ThinkLight

sysfs notes:

The ThinkPad LED sysfs interface is described in detail by the LED class

documentation, in Documentation/leds/leds-class.txt.

documentation, in Documentation/leds/leds-class.rst.

The LEDs are named (in LED ID order, from 0 to 12):

"tpacpi::power", "tpacpi:orange:batt", "tpacpi:green:batt",

:orphan:

====

LEDs

====

.. toctree::

   :maxdepth: 1

   leds-class

   leds-class-flash

   ledtrig-oneshot

   ledtrig-transient

   ledtrig-usbport

   uleds

   leds-blinkm

   leds-lm3556

   leds-lp3944

   leds-lp5521

   leds-lp5523

   leds-lp5562

   leds-lp55xx

   leds-mlxcpld

==================

Leds BlinkM driver

==================

The leds-blinkm driver supports the devices of the BlinkM family.

They are RGB-LED modules driven by a (AT)tiny microcontroller and

a) LED class interface for use with triggers

############################################

The registration follows the scheme:

The registration follows the scheme::

  blinkm-<i2c-bus-nr>-<i2c-device-nr>-<color>

  $ ls -h /sys/class/leds/blinkm-6-*

We can control the colors separated into red, green and blue and

assign triggers on each color.

E.g.:

E.g.::

  $ cat blinkm-6-9-blue/brightness

  05

Currently supported is just setting red, green, blue

and a test sequence.

E.g.:

E.g.::

  $ cat *

  00

as of 6/2012

dl9pf <at> gmx <dot> de

==============================

Flash LED handling under Linux

==============================

Some LED devices provide two modes - torch and flash. In the LED subsystem

those modes are supported by LED class (see Documentation/leds/leds-class.txt)

those modes are supported by LED class (see Documentation/leds/leds-class.rst)

and LED Flash class respectively. The torch mode related features are enabled

by default and the flash ones only if a driver declares it by setting

LED_DEV_CAP_FLASH flag.

Following sysfs attributes are exposed for controlling flash LED devices:

(see Documentation/ABI/testing/sysfs-class-led-flash)

	- flash_brightness

	- max_flash_brightness

	- flash_timeout

The driver must call the v4l2_flash_init function to get registered in the

V4L2 subsystem. The function takes six arguments:

- dev       : flash device, e.g. an I2C device

- of_node   : of_node of the LED, may be NULL if the same as device's

- fled_cdev : LED flash class device to wrap

- iled_cdev : LED flash class device representing indicator LED associated with

- dev:

	flash device, e.g. an I2C device

- of_node:

	of_node of the LED, may be NULL if the same as device's

- fled_cdev:

	LED flash class device to wrap

- iled_cdev:

	LED flash class device representing indicator LED associated with

	fled_cdev, may be NULL

- ops : V4L2 specific ops

	* external_strobe_set - defines the source of the flash LED strobe -

- ops:

	V4L2 specific ops

	* external_strobe_set

		defines the source of the flash LED strobe -

		V4L2_CID_FLASH_STROBE control or external source, typically

		a sensor, which makes it possible to synchronise the flash

		strobe start with exposure start,

	* intensity_to_led_brightness and led_brightness_to_intensity - perform

	* intensity_to_led_brightness and led_brightness_to_intensity

		perform

		enum led_brightness <-> V4L2 intensity conversion in a device

		specific manner - they can be used for devices with non-linear

		LED current scale.

- config : configuration for V4L2 Flash sub-device

	* dev_name - the name of the media entity, unique in the system,

	* flash_faults - bitmask of flash faults that the LED flash class

- config:

	configuration for V4L2 Flash sub-device

	* dev_name

		the name of the media entity, unique in the system,

	* flash_faults

		bitmask of flash faults that the LED flash class

		device can report; corresponding LED_FAULT* bit definitions are

		available in <linux/led-class-flash.h>,

	* torch_intensity - constraints for the LED in TORCH mode

	* torch_intensity

		constraints for the LED in TORCH mode

		in microamperes,

	* indicator_intensity - constraints for the indicator LED

	* indicator_intensity

		constraints for the indicator LED

		in microamperes,

	* has_external_strobe - determines whether the flash strobe source

	* has_external_strobe

		determines whether the flash strobe source

		can be switched to external,

On remove the v4l2_flash_release function has to be called, which takes one

========================

LED handling under Linux

========================

LED subsystem core exposes following API for setting brightness:

    - led_set_brightness : it is guaranteed not to sleep, passing LED_OFF stops

    - led_set_brightness:

		it is guaranteed not to sleep, passing LED_OFF stops

		blinking,

    - led_set_brightness_sync : for use cases when immediate effect is desired -

    - led_set_brightness_sync:

		for use cases when immediate effect is desired -

		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.

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

[devm_]led_classdev_register. If the non devm version is used the driver

`[devm_]led_classdev_register`. If the non devm version is used the driver

must call led_classdev_unregister from its remove function before

free-ing the led_classdev struct.

timers that may have been required for blinking.

The blink_set() function should choose a user friendly blinking value

if it is called with *delay_on==0 && *delay_off==0 parameters. In this

if it is called with `*delay_on==0` && `*delay_off==0` parameters. In this

case the driver should give back the chosen value through delay_on and

delay_off parameters to the leds subsystem.