LED Transient Trigger

Transient trigger가 필요한 이유

기존 LED timer trigger는 one-shot timer 활성화 interface가 없습니다. `delay_on`과 `delay_off`로 on·off 시간을 정하면 trigger를 비활성화할 때까지 cycle이 반복되므로, 한 상태를 딱 한 번 유지한 뒤 영구히 원래 상태로 돌아가는 동작을 직접 표현하지 못합니다.

Userspace가 timer trigger로 비슷한 동작을 만들 수는 있지만 application이 timer를 해제하지 못한 채 crash하거나 종료되면 hardware가 그 상태에 영구히 남을 수 있습니다.

Transient trigger는 한 번만 실행되는 timer를 제공하며 다른 LED trigger와 같은 방식으로 활성화·비활성화할 수 있습니다.

LED class driver 등록 때 지원 trigger와 default trigger를 지정할 수 있고 default의 activation routine이 호출되지만, 등록 자체는 LED 상태를 바꾸지 않습니다. Driver unregister 때는 현재 trigger의 deactivation routine이 호출되고 LED가 `LED_OFF`로 바뀝니다.

=====================
LED Transient Trigger
=====================

The leds timer trigger does not currently have an interface to activate
a one shot timer. The current support allows for setting two timers, one for
specifying how long a state to be on, and the second for how long the state
to be off. The delay_on value specifies the time period an LED should stay
in on state, followed by a delay_off value that specifies how long the LED
should stay in off state. The on and off cycle repeats until the trigger
gets deactivated. There is no provision for one time activation to implement
features that require an on or off state to be held just once and then stay in
the original state forever.

Without one shot timer interface, user space can still use timer trigger to
set a timer to hold a state, however when user space application crashes or
goes away without deactivating the timer, the hardware will be left in that
state permanently.

Transient trigger addresses the need for one shot timer activation. The
transient trigger can be enabled and disabled just like the other leds
triggers.

When an led class device driver registers itself, it can specify all leds
triggers it supports and a default trigger. During registration, activation
routine for the default trigger gets called. During registration of an led
class device, the LED state does not change.

When the driver unregisters, deactivation routine for the currently active
trigger will be called, and LED state is changed to LED_OFF.

Driver suspend changes the LED state to LED_OFF and resume doesn't change

Suspend·resume와 trigger 등록

Driver suspend는 LED를 `LED_OFF`로 바꾸고 resume 자체는 상태를 바꾸지 않습니다. Suspend·resume와 현재 trigger 사이에는 명시적인 상호작용이 없습니다.

Suspend 동안 LED 상태 변경은 멈추지만 이미 active인 timer는 계속 진행됩니다. 이 동안 timer가 hardware LED 상태를 실제로 바꾸지는 못하며, resume 뒤 trigger가 다시 동작합니다.

Brightness는 공통 LED class property입니다. Userspace가 `echo 0 > brightness`를 실행하면 현재 trigger가 비활성화됩니다.

Transient trigger는 표준 register·unregister interface를 사용합니다. 등록 때 default로 지정한 device에서 activation routine이 호출되며 보통 상태는 유지되지만 다른 trigger가 active하면 `LED_OFF`로 바뀝니다. Trigger unregister는 LED를 `LED_OFF`로 바꿉니다.

Activation routine은 LED 상태를 바꾸지 않고 property 생성과 초기화만 수행합니다. Deactivation routine은 active timer를 취소하고 property를 제거한 뒤 non-transient 상태를 복원합니다.

the state. Please note that there is no explicit interaction between the
suspend and resume actions and the currently enabled trigger. LED state
changes are suspended while the driver is in suspend state. Any timers
that are active at the time driver gets suspended, continue to run, without
being able to actually change the LED state. Once driver is resumed, triggers
start functioning again.

LED state changes are controlled using brightness which is a common led
class device property. When brightness is set to 0 from user space via
echo 0 > brightness, it will result in deactivating the current trigger.

Transient trigger uses standard register and unregister interfaces. During
trigger registration, for each led class device that specifies this trigger
as its default trigger, trigger activation routine will get called. During
registration, the LED state does not change, unless there is another trigger
active, in which case LED state changes to LED_OFF.

During trigger unregistration, LED state gets changed to LED_OFF.

Transient trigger activation routine doesn't change the LED state. It
creates its properties and does its initialization. Transient trigger
deactivation routine, will cancel any timer that is active before it cleans
up and removes the properties it created. It will restore the LED state to
non-transient state. When driver gets suspended, irrespective of the transient
state, the LED state changes to LED_OFF.

Transient trigger can be enabled and disabled from user space on led class
devices, that support this trigger as shown below::

        echo transient > trigger
        echo none > trigger

activate·state·duration property

Userspace는 `echo transient > trigger`로 활성화하고 `echo none > trigger`로 비활성화합니다. Trigger가 노출하는 property는 `activate`, `state`, `duration` 세 개이며 활성화 시 기본값으로 초기화됩니다.

`duration`은 millisecond 단위 one-shot timer 값이고 초기값은 0입니다. `activate`는 이 duration을 사용하는 timer를 시작하거나 취소하며 초기·기본값은 0입니다. 먼저 trigger를 활성화한 뒤 duration을 설정할 수 있도록 이렇게 설계되었습니다.

`activate = 1`은 지정 duration timer가 실행 중임을 뜻하고 `0`은 active timer가 없음을 뜻합니다. `duration`을 다시 쓰더라도 이미 실행 중인 timer는 원래 시간으로 계속 실행됩니다.

`state`는 duration 동안 유지할 transient 상태입니다. `0`은 `LED_OFF`, `1`은 `LED_FULL`이며 만료 뒤에는 그 반대인 non-transient 상태로 바뀝니다. 현재 LED 상태는 transient 상태를 적용하기 전에 검사하지 않습니다.

Driver의 `brightness_set()` 구현이 기본 LED polarity를 반대로 mapping할 수 있으므로 실제 hardware level은 driver 정의에 따라 invert될 수 있습니다.

NOTE:
        Add a new property trigger state to control the state.

This trigger exports three properties, activate, state, and duration. When
transient trigger is activated these properties are set to default values.

- duration allows setting timer value in msecs. The initial value is 0.
- activate allows activating and deactivating the timer specified by
  duration as needed. The initial and default value is 0.  This will allow
  duration to be set after trigger activation.
- state allows user to specify a transient state to be held for the specified
  duration.

        activate
              - one shot timer activate mechanism.
                1 when activated, 0 when deactivated.
                default value is zero when transient trigger is enabled,
                to allow duration to be set.

                activate state indicates a timer with a value of specified
                duration running.
                deactivated state indicates that there is no active timer
                running.

        duration
              - one shot timer value. When activate is set, duration value
                is used to start a timer that runs once. This value doesn't
                get changed by the trigger unless user does a set via
                echo new_value > duration

        state
              - transient state to be held. It has two values 0 or 1. 0 maps
                to LED_OFF and 1 maps to LED_FULL. The specified state is
                held for the duration of the one shot timer and then the
                state gets changed to the non-transient state which is the
                inverse of transient state.
                If state = LED_FULL, when the timer runs out the state will
                go back to LED_OFF.
                If state = LED_OFF, when the timer runs out the state will

Timer 만료와 command 의미

Timer가 만료되면 `activate`는 0인 deactivated 상태로 돌아갑니다. `duration`은 설정값을 유지하므로 application은 시간을 한 번만 정한 뒤 필요할 때마다 `activate = 1`로 같은 one-shot을 실행할 수 있습니다.

만료 시 LED는 transient state의 반대인 non-transient state로 복원됩니다. `state = LED_FULL`이었다면 `LED_OFF`, `state = LED_OFF`였다면 `LED_FULL`로 돌아갑니다.

`echo n > duration`이나 `echo 0 > duration`은 다음 activate에 사용할 값만 저장하며 현재 active timer의 남은 시간을 늘리거나 줄이지 않습니다. 이 trigger는 실행 중 timer 연장·단축을 지원하지 않습니다.

                go back to LED_FULL.
                Please note that current LED state is not checked prior to
                changing the state to the specified state.
                Driver could map these values to inverted depending on the
                default states it defines for the LED in its brightness_set()
                interface which is called from the led brightness_set()
                interfaces to control the LED state.

When timer expires activate goes back to deactivated state, duration is left
at the set value to be used when activate is set at a future time. This will
allow user app to set the time once and activate it to run it once for the
specified value as needed. When timer expires, state is restored to the
non-transient state which is the inverse of the transient state:

        =================   ===============================================
        echo 1 > activate   starts timer = duration when duration is not 0.
        echo 0 > activate   cancels currently running timer.
        echo n > duration   stores timer value to be used upon next
                            activate. Currently active timer if
                            any, continues to run for the specified time.
        echo 0 > duration   stores timer value to be used upon next
                            activate. Currently active timer if any,
                            continues to run for the specified time.
        echo 1 > state      stores desired transient state LED_FULL to be
                            held for the specified duration.
        echo 0 > state      stores desired transient state LED_OFF to be
                            held for the specified duration.
        =================   ===============================================

What is not supported
=====================

제약과 활용 사례

지원하지 않는 기능은 active timer의 연장과 단축입니다. Timer activation은 항상 one-shot입니다.

예제는 trigger를 `transient`로 선택하고 duration `n`과 `state = 1`을 저장한 뒤 필요할 때마다 `activate = 1`을 써서 한 번 실행합니다. 작업이 끝나면 `trigger = none`으로 해제합니다.

주요 활용은 userspace activity indicator, application 생존 여부를 나타내는 watchdog indicator, transient GPIO output입니다. Watchdog 용도에서는 application이 살아 있는 동안 LED를 계속 재활성화하고, application이 죽으면 timer 만료로 LED가 자동 소등됩니다.

- Timer activation is one shot and extending and/or shortening the timer
  is not supported.

Examples
========

use-case 1::

        echo transient > trigger
        echo n > duration
        echo 1 > state

repeat the following step as needed::

        echo 1 > activate - start timer = duration to run once
        echo 1 > activate - start timer = duration to run once
        echo none > trigger

This trigger is intended to be used for the following example use cases:

 - Use of LED by user space app as activity indicator.
 - Use of LED by user space app as a kind of watchdog indicator -- as
   long as the app is alive, it can keep the LED illuminated, if it dies
   the LED will be extinguished automatically.
 - Use by any user space app that needs a transient GPIO output.