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