| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113 |
- From 8aa2fd7b66980ecd2e45e95af61cf7eafede1211 Mon Sep 17 00:00:00 2001
- From: Christian Marangi <[email protected]>
- Date: Mon, 29 May 2023 18:32:33 +0200
- Subject: [PATCH 03/13] Documentation: leds: leds-class: Document new Hardware
- driven LEDs APIs
- Document new Hardware driven LEDs APIs.
- 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.
- Add documentation for each required value and API to make hw control
- possible and implementable by both LEDs and triggers.
- Signed-off-by: Christian Marangi <[email protected]>
- Reviewed-by: Andrew Lunn <[email protected]>
- Signed-off-by: David S. Miller <[email protected]>
- ---
- Documentation/leds/leds-class.rst | 81 +++++++++++++++++++++++++++++++
- 1 file changed, 81 insertions(+)
- --- a/Documentation/leds/leds-class.rst
- +++ b/Documentation/leds/leds-class.rst
- @@ -169,6 +169,87 @@ Setting the brightness to zero with brig
- 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
- ============
|
