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