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