1 ===================== 2 LED Transient Trigger 3 ===================== 4 5 The leds timer trigger does not currently have an interface to activate 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 second for how long the state 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 that specifies how long the LED 10 should stay in off state. The on and off cycle repeats until the trigger 11 gets deactivated. There is no provision for one time activation to implement 12 features that require an on or off state to be held just once and then stay in 13 the original state forever. 14 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 space application crashes or 17 goes away without deactivating the timer, the hardware will be left in that 18 state permanently. 19 20 Transient trigger addresses the need for one shot timer activation. The 21 transient trigger can be enabled and disabled just like the other leds 22 triggers. 23 24 When an led class device driver registers itself, it can specify all leds 25 triggers it supports and a default trigger. During registration, activation 26 routine for the default trigger gets called. During registration of an led 27 class device, the LED state does not change. 28 29 When the driver unregisters, deactivation routine for the currently active 30 trigger will be called, and LED state is changed to LED_OFF. 31 32 Driver suspend changes the LED state to LED_OFF and resume doesn't change 33 the state. Please note that there is no explicit interaction between the 34 suspend and resume actions and the currently enabled trigger. LED state 35 changes are suspended while the driver is in suspend state. Any timers 36 that are active at the time driver gets suspended, continue to run, without 37 being able to actually change the LED state. Once driver is resumed, triggers 38 start functioning again. 39 40 LED state changes are controlled using brightness which is a common led 41 class device property. When brightness is set to 0 from user space via 42 echo 0 > brightness, it will result in deactivating the current trigger. 43 44 Transient trigger uses standard register and unregister interfaces. During 45 trigger registration, for each led class device that specifies this trigger 46 as its default trigger, trigger activation routine will get called. During 47 registration, the LED state does not change, unless there is another trigger 48 active, in which case LED state changes to LED_OFF. 49 50 During trigger unregistration, LED state gets changed to LED_OFF. 51 52 Transient trigger activation routine doesn't change the LED state. It 53 creates its properties and does its initialization. Transient trigger 54 deactivation routine, will cancel any timer that is active before it cleans 55 up and removes the properties it created. It will restore the LED state to 56 non-transient state. When driver gets suspended, irrespective of the transient 57 state, the LED state changes to LED_OFF. 58 59 Transient trigger can be enabled and disabled from user space on led class 60 devices, that support this trigger as shown below:: 61 62 echo transient > trigger 63 echo none > trigger 64 65 NOTE: 66 Add a new property trigger state to control the state. 67 68 This trigger exports three properties, activate, state, and duration. When 69 transient 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 112 When timer expires activate goes back to deactivated state, duration is left 113 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 activate it to run it once for the 115 specified value as needed. When timer expires, state is restored to the 116 non-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 133 What is not supported 134 ===================== 135 136 - Timer activation is one shot and extending and/or shortening the timer 137 is not supported. 138 139 Examples 140 ======== 141 142 use-case 1:: 143 144 echo transient > trigger 145 echo n > duration 146 echo 1 > state 147 148 repeat 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 154 This 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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.