Documentation: leds: leds-class: Document new Hardware driven LEDs APIs

should completely turn off the LED and cancel the previously programmed

hardware blinking function, if any.

Hardware driven LEDs

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

Some LEDs can be programmed to be driven by hardware. This is not

limited to blink but also to turn off or on autonomously.

To support this feature, a LED needs to implement various additional

ops and needs to declare specific support for the supported triggers.

With hw control we refer to the LED driven by hardware.

LED driver must define the following value to support hw control:

    - hw_control_trigger:

               unique trigger name supported by the LED in hw control

               mode.

LED driver must implement the following API to support hw control:

    - hw_control_is_supported:

                check if the flags passed by the supported trigger can

                be parsed and activate hw control on the LED.

                Return 0 if the passed flags mask is supported and

                can be set with hw_control_set().

                If the passed flags mask is not supported -EOPNOTSUPP

                must be returned, the LED trigger will use software

                fallback in this case.

                Return a negative error in case of any other error like

                device not ready or timeouts.

     - hw_control_set:

                activate hw control. LED driver will use the provided

                flags passed from the supported trigger, parse them to

                a set of mode and setup the LED to be driven by hardware

                following the requested modes.

                Set LED_OFF via the brightness_set to deactivate hw control.

                Return 0 on success, a negative error number on failing to

                apply flags.

    - hw_control_get:

                get active modes from a LED already in hw control, parse

                them and set in flags the current active flags for the

                supported trigger.

                Return 0 on success, a negative error number on failing

                parsing the initial mode.

                Error from this function is NOT FATAL as the device may

                be in a not supported initial state by the attached LED

                trigger.

    - hw_control_get_device:

                return the device associated with the LED driver in

                hw control. A trigger might use this to match the

                returned device from this function with a configured

                device for the trigger as the source for blinking

                events and correctly enable hw control.

                (example a netdev trigger configured to blink for a

                particular dev match the returned dev from get_device

                to set hw control)

                Returns a pointer to a struct device or NULL if nothing

                is currently attached.

LED driver can activate additional modes by default to workaround the

impossibility of supporting each different mode on the supported trigger.

Examples are hardcoding the blink speed to a set interval, enable special

feature like bypassing blink if some requirements are not met.

A trigger should first check if the hw control API are supported by the LED

driver and check if the trigger is supported to verify if hw control is possible,

use hw_control_is_supported to check if the flags are supported and only at

the end use hw_control_set to activate hw control.

A trigger can use hw_control_get to check if a LED is already in hw control

and init their flags.

When the LED is in hw control, no software blink is possible and doing so

will effectively disable hw control.

Known Issues

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