target/linux/generic/backport-5.15/818-v6.5-03-Documentation-leds-leds-class-Document-new-Hardware-.patch

   1 From 8aa2fd7b66980ecd2e45e95af61cf7eafede1211 Mon Sep 17 00:00:00 2001
   2 From: Christian Marangi <ansuelsmth@gmail.com>
   3 Date: Mon, 29 May 2023 18:32:33 +0200
   4 Subject: [PATCH 03/13] Documentation: leds: leds-class: Document new Hardware
   5  driven LEDs APIs
   6
   7 Document new Hardware driven LEDs APIs.
   8
   9 Some LEDs can be programmed to be driven by hardware. This is not
  10 limited to blink but also to turn off or on autonomously.
  11 To support this feature, a LED needs to implement various additional
  12 ops and needs to declare specific support for the supported triggers.
  13
  14 Add documentation for each required value and API to make hw control
  15 possible and implementable by both LEDs and triggers.
  16
  17 Signed-off-by: Christian Marangi <ansuelsmth@gmail.com>
  18 Reviewed-by: Andrew Lunn <andrew@lunn.ch>
  19 Signed-off-by: David S. Miller <davem@davemloft.net>
  20 ---
  21  Documentation/leds/leds-class.rst | 81 +++++++++++++++++++++++++++++++
  22  1 file changed, 81 insertions(+)
  23
  24 --- a/Documentation/leds/leds-class.rst
  25 +++ b/Documentation/leds/leds-class.rst
  26 @@ -169,6 +169,87 @@ Setting the brightness to zero with brig
  27  should completely turn off the LED and cancel the previously programmed
  28  hardware blinking function, if any.
  29
  30 +Hardware driven LEDs
  31 +====================
  32 +
  33 +Some LEDs can be programmed to be driven by hardware. This is not
  34 +limited to blink but also to turn off or on autonomously.
  35 +To support this feature, a LED needs to implement various additional
  36 +ops and needs to declare specific support for the supported triggers.
  37 +
  38 +With hw control we refer to the LED driven by hardware.
  39 +
  40 +LED driver must define the following value to support hw control:
  41 +
  42 +    - hw_control_trigger:
  43 +               unique trigger name supported by the LED in hw control
  44 +               mode.
  45 +
  46 +LED driver must implement the following API to support hw control:
  47 +    - hw_control_is_supported:
  48 +                check if the flags passed by the supported trigger can
  49 +                be parsed and activate hw control on the LED.
  50 +
  51 +                Return 0 if the passed flags mask is supported and
  52 +                can be set with hw_control_set().
  53 +
  54 +                If the passed flags mask is not supported -EOPNOTSUPP
  55 +                must be returned, the LED trigger will use software
  56 +                fallback in this case.
  57 +
  58 +                Return a negative error in case of any other error like
  59 +                device not ready or timeouts.
  60 +
  61 +     - hw_control_set:
  62 +                activate hw control. LED driver will use the provided
  63 +                flags passed from the supported trigger, parse them to
  64 +                a set of mode and setup the LED to be driven by hardware
  65 +                following the requested modes.
  66 +
  67 +                Set LED_OFF via the brightness_set to deactivate hw control.
  68 +
  69 +                Return 0 on success, a negative error number on failing to
  70 +                apply flags.
  71 +
  72 +    - hw_control_get:
  73 +                get active modes from a LED already in hw control, parse
  74 +                them and set in flags the current active flags for the
  75 +                supported trigger.
  76 +
  77 +                Return 0 on success, a negative error number on failing
  78 +                parsing the initial mode.
  79 +                Error from this function is NOT FATAL as the device may
  80 +                be in a not supported initial state by the attached LED
  81 +                trigger.
  82 +
  83 +    - hw_control_get_device:
  84 +                return the device associated with the LED driver in
  85 +                hw control. A trigger might use this to match the
  86 +                returned device from this function with a configured
  87 +                device for the trigger as the source for blinking
  88 +                events and correctly enable hw control.
  89 +                (example a netdev trigger configured to blink for a
  90 +                particular dev match the returned dev from get_device
  91 +                to set hw control)
  92 +
  93 +                Returns a pointer to a struct device or NULL if nothing
  94 +                is currently attached.
  95 +
  96 +LED driver can activate additional modes by default to workaround the
  97 +impossibility of supporting each different mode on the supported trigger.
  98 +Examples are hardcoding the blink speed to a set interval, enable special
  99 +feature like bypassing blink if some requirements are not met.
 100 +
 101 +A trigger should first check if the hw control API are supported by the LED
 102 +driver and check if the trigger is supported to verify if hw control is possible,
 103 +use hw_control_is_supported to check if the flags are supported and only at
 104 +the end use hw_control_set to activate hw control.
 105 +
 106 +A trigger can use hw_control_get to check if a LED is already in hw control
 107 +and init their flags.
 108 +
 109 +When the LED is in hw control, no software blink is possible and doing so
 110 +will effectively disable hw control.
 111
 112  Known Issues
 113  ============