tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
leds: add new transient trigger for one shot timer activation
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.
As a specific example of this use-case, let's look at vibrate feature on
phones. Vibrate function on phones is implemented using PWM pins on SoC
or PMIC. There is a need to activate one shot timer to control the
vibrate feature, to prevent user space crashes leaving the phone in
vibrate mode permanently causing the battery to drain.
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.
Signed-off-by: Shuah Khan <shuahkhan@gmail.com>
Cc: Jonas Bonn <jonas@southpole.se>
Cc: Richard Purdie <rpurdie@rpsys.net>
Cc: NeilBrown <neilb@suse.de>
Cc: Bryan Wu <bryan.wu@canonical.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
authored by
Shuah Khan
and committed by
Linus Torvalds
44e1e9f8
49dca5ae
+398
+152
Documentation/leds/ledtrig-transient.txt
+152
Documentation/leds/ledtrig-transient.txt
···
1
+
LED Transient Trigger
2
+
=====================
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
+
14
+
Without one shot timer interface, user space can still use timer trigger to
15
+
set a timer to hold a state, however when user space application crashes or
16
+
goes away without deactivating the timer, the hardware will be left in that
17
+
state permanently.
18
+
19
+
As a specific example of this use-case, let's look at vibrate feature on
20
+
phones. Vibrate function on phones is implemented using PWM pins on SoC or
21
+
PMIC. There is a need to activate one shot timer to control the vibrate
22
+
feature, to prevent user space crashes leaving the phone in vibrate mode
23
+
permanently causing the battery to drain.
24
+
25
+
Transient trigger addresses the need for one shot timer activation. The
26
+
transient trigger can be enabled and disabled just like the other leds
27
+
triggers.
28
+
29
+
When an led class device driver registers itself, it can specify all leds
30
+
triggers it supports and a default trigger. During registration, activation
31
+
routine for the default trigger gets called. During registration of an led
32
+
class device, the LED state does not change.
33
+
34
+
When the driver unregisters, deactivation routine for the currently active
35
+
trigger will be called, and LED state is changed to LED_OFF.
36
+
37
+
Driver suspend changes the LED state to LED_OFF and resume doesn't change
38
+
the state. Please note that there is no explicit interaction between the
39
+
suspend and resume actions and the currently enabled trigger. LED state
40
+
changes are suspended while the driver is in suspend state. Any timers
41
+
that are active at the time driver gets suspended, continue to run, without
42
+
being able to actually change the LED state. Once driver is resumed, triggers
43
+
start functioning again.
44
+
45
+
LED state changes are controlled using brightness which is a common led
46
+
class device property. When brightness is set to 0 from user space via
47
+
echo 0 > brightness, it will result in deactivating the current trigger.
48
+
49
+
Transient trigger uses standard register and unregister interfaces. During
50
+
trigger registration, for each led class device that specifies this trigger
51
+
as its default trigger, trigger activation routine will get called. During
52
+
registration, the LED state does not change, unless there is another trigger
53
+
active, in which case LED state changes to LED_OFF.
54
+
55
+
During trigger unregistration, LED state gets changed to LED_OFF.
56
+
57
+
Transient trigger activation routine doesn't change the LED state. It
58
+
creates its properties and does its initialization. Transient trigger
59
+
deactivation routine, will cancel any timer that is active before it cleans
60
+
up and removes the properties it created. It will restore the LED state to
61
+
non-transient state. When driver gets suspended, irrespective of the transient
62
+
state, the LED state changes to LED_OFF.
63
+
64
+
Transient trigger can be enabled and disabled from user space on led class
65
+
devices, that support this trigger as shown below:
66
+
67
+
echo transient > trigger
68
+
echo none > trigger
69
+
70
+
NOTE: Add a new property trigger state to control the state.
71
+
72
+
This trigger exports three properties, activate, state, and duration. When
73
+
transient trigger is activated these properties are set to default values.
74
+
75
+
- duration allows setting timer value in msecs. The initial value is 0.
76
+
- activate allows activating and deactivating the timer specified by
77
+
duration as needed. The initial and default value is 0. This will allow
78
+
duration to be set after trigger activation.
79
+
- state allows user to specify a transient state to be held for the specified
80
+
duration.
81
+
82
+
activate - one shot timer activate mechanism.
83
+
1 when activated, 0 when deactivated.
84
+
default value is zero when transient trigger is enabled,
85
+
to allow duration to be set.
86
+
87
+
activate state indicates a timer with a value of specified
88
+
duration running.
89
+
deactivated state indicates that there is no active timer
90
+
running.
91
+
92
+
duration - one shot timer value. When activate is set, duration value
93
+
is used to start a timer that runs once. This value doesn't
94
+
get changed by the trigger unless user does a set via
95
+
echo new_value > duration
96
+
97
+
state - transient state to be held. It has two values 0 or 1. 0 maps
98
+
to LED_OFF and 1 maps to LED_FULL. The specified state is
99
+
held for the duration of the one shot timer and then the
100
+
state gets changed to the non-transient state which is the
101
+
inverse of transient state.
102
+
If state = LED_FULL, when the timer runs out the state will
103
+
go back to LED_OFF.
104
+
If state = LED_OFF, when the timer runs out the state will
105
+
go back to LED_FULL.
106
+
Please note that current LED state is not checked prior to
107
+
changing the state to the specified state.
108
+
Driver could map these values to inverted depending on the
109
+
default states it defines for the LED in its brightness_set()
110
+
interface which is called from the led brightness_set()
111
+
interfaces to control the LED state.
112
+
113
+
When timer expires activate goes back to deactivated state, duration is left
114
+
at the set value to be used when activate is set at a future time. This will
115
+
allow user app to set the time once and activate it to run it once for the
116
+
specified value as needed. When timer expires, state is restored to the
117
+
non-transient state which is the inverse of the transient state.
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
+
What is not supported:
133
+
======================
134
+
- Timer activation is one shot and extending and/or shortening the timer
135
+
is not supported.
136
+
137
+
Example use-case 1:
138
+
echo transient > trigger
139
+
echo n > duration
140
+
echo 1 > state
141
+
repeat the following step as needed:
142
+
echo 1 > activate - start timer = duration to run once
143
+
echo 1 > activate - start timer = duration to run once
144
+
echo none > trigger
145
+
146
+
This trigger is intended to be used for for the following example use cases:
147
+
- Control of vibrate (phones, tablets etc.) hardware by user space app.
148
+
- Use of LED by user space app as activity indicator.
149
+
- Use of LED by user space app as a kind of watchdog indicator -- as
150
+
long as the app is alive, it can keep the LED illuminated, if it dies
151
+
the LED will be extinguished automatically.
152
+
- Use by any user space app that needs a transient GPIO output.
+8
drivers/leds/Kconfig
+8
drivers/leds/Kconfig
···
479
479
comment "iptables trigger is under Netfilter config (LED target)"
480
480
depends on LEDS_TRIGGERS
481
481
482
+
config LEDS_TRIGGER_TRANSIENT
483
+
tristate "LED Transient Trigger"
484
+
depends on LEDS_TRIGGERS
485
+
help
486
+
This allows one time activation of a transient state on
487
+
GPIO/PWM based hadrware.
488
+
If unsure, say Y.
489
+
482
490
endif # NEW_LEDS
+1
drivers/leds/Makefile
+1
drivers/leds/Makefile
+237
drivers/leds/ledtrig-transient.c
+237
drivers/leds/ledtrig-transient.c
···
1
+
/*
2
+
* LED Kernel Transient Trigger
3
+
*
4
+
* Copyright (C) 2012 Shuah Khan <shuahkhan@gmail.com>
5
+
*
6
+
* Based on Richard Purdie's ledtrig-timer.c and Atsushi Nemoto's
7
+
* ledtrig-heartbeat.c
8
+
* Design and use-case input from Jonas Bonn <jonas@southpole.se> and
9
+
* Neil Brown <neilb@suse.de>
10
+
*
11
+
* This program is free software; you can redistribute it and/or modify
12
+
* it under the terms of the GNU General Public License version 2 as
13
+
* published by the Free Software Foundation.
14
+
*
15
+
*/
16
+
/*
17
+
* Transient trigger allows one shot timer activation. Please refer to
18
+
* Documentation/leds/ledtrig-transient.txt for details
19
+
*/
20
+
21
+
#include <linux/module.h>
22
+
#include <linux/kernel.h>
23
+
#include <linux/init.h>
24
+
#include <linux/device.h>
25
+
#include <linux/slab.h>
26
+
#include <linux/timer.h>
27
+
#include <linux/leds.h>
28
+
#include "leds.h"
29
+
30
+
struct transient_trig_data {
31
+
int activate;
32
+
int state;
33
+
int restore_state;
34
+
unsigned long duration;
35
+
struct timer_list timer;
36
+
};
37
+
38
+
static void transient_timer_function(unsigned long data)
39
+
{
40
+
struct led_classdev *led_cdev = (struct led_classdev *) data;
41
+
struct transient_trig_data *transient_data = led_cdev->trigger_data;
42
+
43
+
transient_data->activate = 0;
44
+
led_set_brightness(led_cdev, transient_data->restore_state);
45
+
}
46
+
47
+
static ssize_t transient_activate_show(struct device *dev,
48
+
struct device_attribute *attr, char *buf)
49
+
{
50
+
struct led_classdev *led_cdev = dev_get_drvdata(dev);
51
+
struct transient_trig_data *transient_data = led_cdev->trigger_data;
52
+
53
+
return sprintf(buf, "%d\n", transient_data->activate);
54
+
}
55
+
56
+
static ssize_t transient_activate_store(struct device *dev,
57
+
struct device_attribute *attr, const char *buf, size_t size)
58
+
{
59
+
struct led_classdev *led_cdev = dev_get_drvdata(dev);
60
+
struct transient_trig_data *transient_data = led_cdev->trigger_data;
61
+
unsigned long state;
62
+
ssize_t ret;
63
+
64
+
ret = kstrtoul(buf, 10, &state);
65
+
if (ret)
66
+
return ret;
67
+
68
+
if (state != 1 && state != 0)
69
+
return -EINVAL;
70
+
71
+
/* cancel the running timer */
72
+
if (state == 0 && transient_data->activate == 1) {
73
+
del_timer(&transient_data->timer);
74
+
transient_data->activate = state;
75
+
led_set_brightness(led_cdev, transient_data->restore_state);
76
+
return size;
77
+
}
78
+
79
+
/* start timer if there is no active timer */
80
+
if (state == 1 && transient_data->activate == 0 &&
81
+
transient_data->duration != 0) {
82
+
transient_data->activate = state;
83
+
led_set_brightness(led_cdev, transient_data->state);
84
+
transient_data->restore_state =
85
+
(transient_data->state == LED_FULL) ? LED_OFF : LED_FULL;
86
+
mod_timer(&transient_data->timer,
87
+
jiffies + transient_data->duration);
88
+
}
89
+
90
+
/* state == 0 && transient_data->activate == 0
91
+
timer is not active - just return */
92
+
/* state == 1 && transient_data->activate == 1
93
+
timer is already active - just return */
94
+
95
+
return size;
96
+
}
97
+
98
+
static ssize_t transient_duration_show(struct device *dev,
99
+
struct device_attribute *attr, char *buf)
100
+
{
101
+
struct led_classdev *led_cdev = dev_get_drvdata(dev);
102
+
struct transient_trig_data *transient_data = led_cdev->trigger_data;
103
+
104
+
return sprintf(buf, "%lu\n", transient_data->duration);
105
+
}
106
+
107
+
static ssize_t transient_duration_store(struct device *dev,
108
+
struct device_attribute *attr, const char *buf, size_t size)
109
+
{
110
+
struct led_classdev *led_cdev = dev_get_drvdata(dev);
111
+
struct transient_trig_data *transient_data = led_cdev->trigger_data;
112
+
unsigned long state;
113
+
ssize_t ret;
114
+
115
+
ret = kstrtoul(buf, 10, &state);
116
+
if (ret)
117
+
return ret;
118
+
119
+
transient_data->duration = state;
120
+
return size;
121
+
}
122
+
123
+
static ssize_t transient_state_show(struct device *dev,
124
+
struct device_attribute *attr, char *buf)
125
+
{
126
+
struct led_classdev *led_cdev = dev_get_drvdata(dev);
127
+
struct transient_trig_data *transient_data = led_cdev->trigger_data;
128
+
int state;
129
+
130
+
state = (transient_data->state == LED_FULL) ? 1 : 0;
131
+
return sprintf(buf, "%d\n", state);
132
+
}
133
+
134
+
static ssize_t transient_state_store(struct device *dev,
135
+
struct device_attribute *attr, const char *buf, size_t size)
136
+
{
137
+
struct led_classdev *led_cdev = dev_get_drvdata(dev);
138
+
struct transient_trig_data *transient_data = led_cdev->trigger_data;
139
+
unsigned long state;
140
+
ssize_t ret;
141
+
142
+
ret = kstrtoul(buf, 10, &state);
143
+
if (ret)
144
+
return ret;
145
+
146
+
if (state != 1 && state != 0)
147
+
return -EINVAL;
148
+
149
+
transient_data->state = (state == 1) ? LED_FULL : LED_OFF;
150
+
return size;
151
+
}
152
+
153
+
static DEVICE_ATTR(activate, 0644, transient_activate_show,
154
+
transient_activate_store);
155
+
static DEVICE_ATTR(duration, 0644, transient_duration_show,
156
+
transient_duration_store);
157
+
static DEVICE_ATTR(state, 0644, transient_state_show, transient_state_store);
158
+
159
+
static void transient_trig_activate(struct led_classdev *led_cdev)
160
+
{
161
+
int rc;
162
+
struct transient_trig_data *tdata;
163
+
164
+
tdata = kzalloc(sizeof(struct transient_trig_data), GFP_KERNEL);
165
+
if (!tdata) {
166
+
dev_err(led_cdev->dev,
167
+
"unable to allocate transient trigger\n");
168
+
return;
169
+
}
170
+
led_cdev->trigger_data = tdata;
171
+
172
+
rc = device_create_file(led_cdev->dev, &dev_attr_activate);
173
+
if (rc)
174
+
goto err_out;
175
+
176
+
rc = device_create_file(led_cdev->dev, &dev_attr_duration);
177
+
if (rc)
178
+
goto err_out_duration;
179
+
180
+
rc = device_create_file(led_cdev->dev, &dev_attr_state);
181
+
if (rc)
182
+
goto err_out_state;
183
+
184
+
setup_timer(&tdata->timer, transient_timer_function,
185
+
(unsigned long) led_cdev);
186
+
led_cdev->activated = true;
187
+
188
+
return;
189
+
190
+
err_out_state:
191
+
device_remove_file(led_cdev->dev, &dev_attr_duration);
192
+
err_out_duration:
193
+
device_remove_file(led_cdev->dev, &dev_attr_activate);
194
+
err_out:
195
+
dev_err(led_cdev->dev, "unable to register transient trigger\n");
196
+
led_cdev->trigger_data = NULL;
197
+
kfree(tdata);
198
+
}
199
+
200
+
static void transient_trig_deactivate(struct led_classdev *led_cdev)
201
+
{
202
+
struct transient_trig_data *transient_data = led_cdev->trigger_data;
203
+
204
+
if (led_cdev->activated) {
205
+
del_timer_sync(&transient_data->timer);
206
+
led_set_brightness(led_cdev, transient_data->restore_state);
207
+
device_remove_file(led_cdev->dev, &dev_attr_activate);
208
+
device_remove_file(led_cdev->dev, &dev_attr_duration);
209
+
device_remove_file(led_cdev->dev, &dev_attr_state);
210
+
led_cdev->trigger_data = NULL;
211
+
led_cdev->activated = false;
212
+
kfree(transient_data);
213
+
}
214
+
}
215
+
216
+
static struct led_trigger transient_trigger = {
217
+
.name = "transient",
218
+
.activate = transient_trig_activate,
219
+
.deactivate = transient_trig_deactivate,
220
+
};
221
+
222
+
static int __init transient_trig_init(void)
223
+
{
224
+
return led_trigger_register(&transient_trigger);
225
+
}
226
+
227
+
static void __exit transient_trig_exit(void)
228
+
{
229
+
led_trigger_unregister(&transient_trigger);
230
+
}
231
+
232
+
module_init(transient_trig_init);
233
+
module_exit(transient_trig_exit);
234
+
235
+
MODULE_AUTHOR("Shuah Khan <shuahkhan@gmail.com>");
236
+
MODULE_DESCRIPTION("Transient LED trigger");
237
+
MODULE_LICENSE("GPL");