ledtrig-transient.rst 6.9 KB

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