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