0001 =====================
0002 LED Transient Trigger
0003 =====================
0004
0005 The leds timer trigger does not currently have an interface to activate
0006 a one shot timer. The current support allows for setting two timers, one for
0007 specifying how long a state to be on, and the second for how long the state
0008 to be off. The delay_on value specifies the time period an LED should stay
0009 in on state, followed by a delay_off value that specifies how long the LED
0010 should stay in off state. The on and off cycle repeats until the trigger
0011 gets deactivated. There is no provision for one time activation to implement
0012 features that require an on or off state to be held just once and then stay in
0013 the original state forever.
0014
0015 Without one shot timer interface, user space can still use timer trigger to
0016 set a timer to hold a state, however when user space application crashes or
0017 goes away without deactivating the timer, the hardware will be left in that
0018 state permanently.
0019
0020 Transient trigger addresses the need for one shot timer activation. The
0021 transient trigger can be enabled and disabled just like the other leds
0022 triggers.
0023
0024 When an led class device driver registers itself, it can specify all leds
0025 triggers it supports and a default trigger. During registration, activation
0026 routine for the default trigger gets called. During registration of an led
0027 class device, the LED state does not change.
0028
0029 When the driver unregisters, deactivation routine for the currently active
0030 trigger will be called, and LED state is changed to LED_OFF.
0031
0032 Driver suspend changes the LED state to LED_OFF and resume doesn't change
0033 the state. Please note that there is no explicit interaction between the
0034 suspend and resume actions and the currently enabled trigger. LED state
0035 changes are suspended while the driver is in suspend state. Any timers
0036 that are active at the time driver gets suspended, continue to run, without
0037 being able to actually change the LED state. Once driver is resumed, triggers
0038 start functioning again.
0039
0040 LED state changes are controlled using brightness which is a common led
0041 class device property. When brightness is set to 0 from user space via
0042 echo 0 > brightness, it will result in deactivating the current trigger.
0043
0044 Transient trigger uses standard register and unregister interfaces. During
0045 trigger registration, for each led class device that specifies this trigger
0046 as its default trigger, trigger activation routine will get called. During
0047 registration, the LED state does not change, unless there is another trigger
0048 active, in which case LED state changes to LED_OFF.
0049
0050 During trigger unregistration, LED state gets changed to LED_OFF.
0051
0052 Transient trigger activation routine doesn't change the LED state. It
0053 creates its properties and does its initialization. Transient trigger
0054 deactivation routine, will cancel any timer that is active before it cleans
0055 up and removes the properties it created. It will restore the LED state to
0056 non-transient state. When driver gets suspended, irrespective of the transient
0057 state, the LED state changes to LED_OFF.
0058
0059 Transient trigger can be enabled and disabled from user space on led class
0060 devices, that support this trigger as shown below::
0061
0062 echo transient > trigger
0063 echo none > trigger
0064
0065 NOTE:
0066 Add a new property trigger state to control the state.
0067
0068 This trigger exports three properties, activate, state, and duration. When
0069 transient trigger is activated these properties are set to default values.
0070
0071 - duration allows setting timer value in msecs. The initial value is 0.
0072 - activate allows activating and deactivating the timer specified by
0073 duration as needed. The initial and default value is 0. This will allow
0074 duration to be set after trigger activation.
0075 - state allows user to specify a transient state to be held for the specified
0076 duration.
0077
0078 activate
0079 - one shot timer activate mechanism.
0080 1 when activated, 0 when deactivated.
0081 default value is zero when transient trigger is enabled,
0082 to allow duration to be set.
0083
0084 activate state indicates a timer with a value of specified
0085 duration running.
0086 deactivated state indicates that there is no active timer
0087 running.
0088
0089 duration
0090 - one shot timer value. When activate is set, duration value
0091 is used to start a timer that runs once. This value doesn't
0092 get changed by the trigger unless user does a set via
0093 echo new_value > duration
0094
0095 state
0096 - transient state to be held. It has two values 0 or 1. 0 maps
0097 to LED_OFF and 1 maps to LED_FULL. The specified state is
0098 held for the duration of the one shot timer and then the
0099 state gets changed to the non-transient state which is the
0100 inverse of transient state.
0101 If state = LED_FULL, when the timer runs out the state will
0102 go back to LED_OFF.
0103 If state = LED_OFF, when the timer runs out the state will
0104 go back to LED_FULL.
0105 Please note that current LED state is not checked prior to
0106 changing the state to the specified state.
0107 Driver could map these values to inverted depending on the
0108 default states it defines for the LED in its brightness_set()
0109 interface which is called from the led brightness_set()
0110 interfaces to control the LED state.
0111
0112 When timer expires activate goes back to deactivated state, duration is left
0113 at the set value to be used when activate is set at a future time. This will
0114 allow user app to set the time once and activate it to run it once for the
0115 specified value as needed. When timer expires, state is restored to the
0116 non-transient state which is the inverse of the transient state:
0117
0118 ================= ===============================================
0119 echo 1 > activate starts timer = duration when duration is not 0.
0120 echo 0 > activate cancels currently running timer.
0121 echo n > duration stores timer value to be used upon next
0122 activate. Currently active timer if
0123 any, continues to run for the specified time.
0124 echo 0 > duration stores timer value to be used upon next
0125 activate. Currently active timer if any,
0126 continues to run for the specified time.
0127 echo 1 > state stores desired transient state LED_FULL to be
0128 held for the specified duration.
0129 echo 0 > state stores desired transient state LED_OFF to be
0130 held for the specified duration.
0131 ================= ===============================================
0132
0133 What is not supported
0134 =====================
0135
0136 - Timer activation is one shot and extending and/or shortening the timer
0137 is not supported.
0138
0139 Examples
0140 ========
0141
0142 use-case 1::
0143
0144 echo transient > trigger
0145 echo n > duration
0146 echo 1 > state
0147
0148 repeat the following step as needed::
0149
0150 echo 1 > activate - start timer = duration to run once
0151 echo 1 > activate - start timer = duration to run once
0152 echo none > trigger
0153
0154 This trigger is intended to be used for the following example use cases:
0155
0156 - Use of LED by user space app as activity indicator.
0157 - Use of LED by user space app as a kind of watchdog indicator -- as
0158 long as the app is alive, it can keep the LED illuminated, if it dies
0159 the LED will be extinguished automatically.
0160 - Use by any user space app that needs a transient GPIO output.
