Documentation/leds/ledtrig-transient.rst

   1 =====================
   2 LED Transient Trigger
   3 =====================
   4
   5 The leds timer trigger does not currently have an interface to activate
   6 a one shot timer. The current support allows for setting two timers, one for
   7 specifying how long a state to be on, and the second for how long the state
   8 to be off. The delay_on value specifies the time period an LED should stay
   9 in on state, followed by a delay_off value that specifies how long the LED
  10 should stay in off state. The on and off cycle repeats until the trigger
  11 gets deactivated. There is no provision for one time activation to implement
  12 features that require an on or off state to be held just once and then stay in
  13 the original state forever.
  14
  15 Without one shot timer interface, user space can still use timer trigger to
  16 set a timer to hold a state, however when user space application crashes or
  17 goes away without deactivating the timer, the hardware will be left in that
  18 state permanently.
  19
  20 As a specific example of this use-case, let's look at vibrate feature on
  21 phones. Vibrate function on phones is implemented using PWM pins on SoC or
  22 PMIC. There is a need to activate one shot timer to control the vibrate
  23 feature, to prevent user space crashes leaving the phone in vibrate mode
  24 permanently causing the battery to drain.
  25
  26 Transient trigger addresses the need for one shot timer activation. The
  27 transient trigger can be enabled and disabled just like the other leds
  28 triggers.
  29
  30 When an led class device driver registers itself, it can specify all leds
  31 triggers it supports and a default trigger. During registration, activation
  32 routine for the default trigger gets called. During registration of an led
  33 class device, the LED state does not change.
  34
  35 When the driver unregisters, deactivation routine for the currently active
  36 trigger will be called, and LED state is changed to LED_OFF.
  37
  38 Driver suspend changes the LED state to LED_OFF and resume doesn't change
  39 the state. Please note that there is no explicit interaction between the
  40 suspend and resume actions and the currently enabled trigger. LED state
  41 changes are suspended while the driver is in suspend state. Any timers
  42 that are active at the time driver gets suspended, continue to run, without
  43 being able to actually change the LED state. Once driver is resumed, triggers
  44 start functioning again.
  45
  46 LED state changes are controlled using brightness which is a common led
  47 class device property. When brightness is set to 0 from user space via
  48 echo 0 > brightness, it will result in deactivating the current trigger.
  49
  50 Transient trigger uses standard register and unregister interfaces. During
  51 trigger registration, for each led class device that specifies this trigger
  52 as its default trigger, trigger activation routine will get called. During
  53 registration, the LED state does not change, unless there is another trigger
  54 active, in which case LED state changes to LED_OFF.
  55
  56 During trigger unregistration, LED state gets changed to LED_OFF.
  57
  58 Transient trigger activation routine doesn't change the LED state. It
  59 creates its properties and does its initialization. Transient trigger
  60 deactivation routine, will cancel any timer that is active before it cleans
  61 up and removes the properties it created. It will restore the LED state to
  62 non-transient state. When driver gets suspended, irrespective of the transient
  63 state, the LED state changes to LED_OFF.
  64
  65 Transient trigger can be enabled and disabled from user space on led class
  66 devices, that support this trigger as shown below::
  67
  68         echo transient > trigger
  69         echo none > trigger
  70
  71 NOTE:
  72         Add a new property trigger state to control the state.
  73
  74 This trigger exports three properties, activate, state, and duration. When
  75 transient trigger is activated these properties are set to default values.
  76
  77 - duration allows setting timer value in msecs. The initial value is 0.
  78 - activate allows activating and deactivating the timer specified by
  79   duration as needed. The initial and default value is 0.  This will allow
  80   duration to be set after trigger activation.
  81 - state allows user to specify a transient state to be held for the specified
  82   duration.
  83
  84         activate
  85               - one shot timer activate mechanism.
  86                 1 when activated, 0 when deactivated.
  87                 default value is zero when transient trigger is enabled,
  88                 to allow duration to be set.
  89
  90                 activate state indicates a timer with a value of specified
  91                 duration running.
  92                 deactivated state indicates that there is no active timer
  93                 running.
  94
  95         duration
  96               - one shot timer value. When activate is set, duration value
  97                 is used to start a timer that runs once. This value doesn't
  98                 get changed by the trigger unless user does a set via
  99                 echo new_value > duration
 100
 101         state
 102               - transient state to be held. It has two values 0 or 1. 0 maps
 103                 to LED_OFF and 1 maps to LED_FULL. The specified state is
 104                 held for the duration of the one shot timer and then the
 105                 state gets changed to the non-transient state which is the
 106                 inverse of transient state.
 107                 If state = LED_FULL, when the timer runs out the state will
 108                 go back to LED_OFF.
 109                 If state = LED_OFF, when the timer runs out the state will
 110                 go back to LED_FULL.
 111                 Please note that current LED state is not checked prior to
 112                 changing the state to the specified state.
 113                 Driver could map these values to inverted depending on the
 114                 default states it defines for the LED in its brightness_set()
 115                 interface which is called from the led brightness_set()
 116                 interfaces to control the LED state.
 117
 118 When timer expires activate goes back to deactivated state, duration is left
 119 at the set value to be used when activate is set at a future time. This will
 120 allow user app to set the time once and activate it to run it once for the
 121 specified value as needed. When timer expires, state is restored to the
 122 non-transient state which is the inverse of the transient state:
 123
 124         =================   ===============================================
 125         echo 1 > activate   starts timer = duration when duration is not 0.
 126         echo 0 > activate   cancels currently running timer.
 127         echo n > duration   stores timer value to be used upon next
 128                             activate. Currently active timer if
 129                             any, continues to run for the specified time.
 130         echo 0 > duration   stores timer value to be used upon next
 131                             activate. Currently active timer if any,
 132                             continues to run for the specified time.
 133         echo 1 > state      stores desired transient state LED_FULL to be
 134                             held for the specified duration.
 135         echo 0 > state      stores desired transient state LED_OFF to be
 136                             held for the specified duration.
 137         =================   ===============================================
 138
 139 What is not supported
 140 =====================
 141
 142 - Timer activation is one shot and extending and/or shortening the timer
 143   is not supported.
 144
 145 Examples
 146 ========
 147
 148 use-case 1::
 149
 150         echo transient > trigger
 151         echo n > duration
 152         echo 1 > state
 153
 154 repeat the following step as needed::
 155
 156         echo 1 > activate - start timer = duration to run once
 157         echo 1 > activate - start timer = duration to run once
 158         echo none > trigger
 159
 160 This trigger is intended to be used for for the following example use cases:
 161
 162  - Control of vibrate (phones, tablets etc.) hardware by user space app.
 163  - Use of LED by user space app as activity indicator.
 164  - Use of LED by user space app as a kind of watchdog indicator -- as
 165    long as the app is alive, it can keep the LED illuminated, if it dies
 166    the LED will be extinguished automatically.
 167  - Use by any user space app that needs a transient GPIO output.