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 20As a specific example of this use-case, let's look at vibrate feature on 21phones. Vibrate function on phones is implemented using PWM pins on SoC or 22PMIC. There is a need to activate one shot timer to control the vibrate 23feature, to prevent user space crashes leaving the phone in vibrate mode 24permanently causing the battery to drain. 25 26Transient trigger addresses the need for one shot timer activation. The 27transient trigger can be enabled and disabled just like the other leds 28triggers. 29 30When an led class device driver registers itself, it can specify all leds 31triggers it supports and a default trigger. During registration, activation 32routine for the default trigger gets called. During registration of an led 33class device, the LED state does not change. 34 35When the driver unregisters, deactivation routine for the currently active 36trigger will be called, and LED state is changed to LED_OFF. 37 38Driver suspend changes the LED state to LED_OFF and resume doesn't change 39the state. Please note that there is no explicit interaction between the 40suspend and resume actions and the currently enabled trigger. LED state 41changes are suspended while the driver is in suspend state. Any timers 42that are active at the time driver gets suspended, continue to run, without 43being able to actually change the LED state. Once driver is resumed, triggers 44start functioning again. 45 46LED state changes are controlled using brightness which is a common led 47class device property. When brightness is set to 0 from user space via 48echo 0 > brightness, it will result in deactivating the current trigger. 49 50Transient trigger uses standard register and unregister interfaces. During 51trigger registration, for each led class device that specifies this trigger 52as its default trigger, trigger activation routine will get called. During 53registration, the LED state does not change, unless there is another trigger 54active, in which case LED state changes to LED_OFF. 55 56During trigger unregistration, LED state gets changed to LED_OFF. 57 58Transient trigger activation routine doesn't change the LED state. It 59creates its properties and does its initialization. Transient trigger 60deactivation routine, will cancel any timer that is active before it cleans 61up and removes the properties it created. It will restore the LED state to 62non-transient state. When driver gets suspended, irrespective of the transient 63state, the LED state changes to LED_OFF. 64 65Transient trigger can be enabled and disabled from user space on led class 66devices, that support this trigger as shown below:: 67 68 echo transient > trigger 69 echo none > trigger 70 71NOTE: 72 Add a new property trigger state to control the state. 73 74This trigger exports three properties, activate, state, and duration. When 75transient 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 118When timer expires activate goes back to deactivated state, duration is left 119at the set value to be used when activate is set at a future time. This will 120allow user app to set the time once and activate it to run it once for the 121specified value as needed. When timer expires, state is restored to the 122non-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 139What is not supported 140===================== 141 142- Timer activation is one shot and extending and/or shortening the timer 143 is not supported. 144 145Examples 146======== 147 148use-case 1:: 149 150 echo transient > trigger 151 echo n > duration 152 echo 1 > state 153 154repeat 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 160This trigger is intended to be used 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. 168