linux-imx
Public
Source
committed c571123c8a91
+
======================================1
2
Pulse Width Modulation (PWM) interface3
+
======================================2
4
3
5
This provides an overview about the Linux PWM interface4
6
5
7
PWMs are commonly used for controlling LEDs, fans or vibrators in6
8
cell phones. PWMs with a fixed purpose have no need implementing7
9
the Linux PWM API (although they could). However, PWMs are often8
10
found as discrete devices on SoCs which have no fixed purpose. It's9
11
up to the board designer to connect them to LEDs or fans. To provide10
12
this kind of flexibility the generic PWM API exists.11
13
12
14
Identifying PWMs13
15
----------------14
16
15
17
Users of the legacy PWM API use unique IDs to refer to PWM devices.16
18
17
19
Instead of referring to a PWM device via its unique ID, board setup code18
20
should instead register a static mapping that can be used to match PWM19
-
consumers to providers, as given in the following example:21
+
consumers to providers, as given in the following example::20
22
21
23
static struct pwm_lookup board_pwm_lookup[] = {22
24
PWM_LOOKUP("tegra-pwm", 0, "pwm-backlight", NULL,23
25
50000, PWM_POLARITY_NORMAL),24
26
};25
27
26
28
static void __init board_init(void)27
29
{28
30
...29
31
pwm_add_table(board_pwm_lookup, ARRAY_SIZE(board_pwm_lookup));33
35
Using PWMs34
36
----------35
37
36
38
Legacy users can request a PWM device using pwm_request() and free it37
39
after usage with pwm_free().38
40
39
41
New users should use the pwm_get() function and pass to it the consumer40
42
device or a consumer name. pwm_put() is used to free the PWM device. Managed41
43
variants of these functions, devm_pwm_get() and devm_pwm_put(), also exist.42
44
43
-
After being requested, a PWM has to be configured using:45
+
After being requested, a PWM has to be configured using::44
46
45
-
int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state);47
+
int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state);46
48
47
49
This API controls both the PWM period/duty_cycle config and the48
50
enable/disable state.49
51
50
52
The pwm_config(), pwm_enable() and pwm_disable() functions are just wrappers51
53
around pwm_apply_state() and should not be used if the user wants to change52
54
several parameter at once. For example, if you see pwm_config() and53
55
pwm_{enable,disable}() calls in the same function, this probably means you54
56
should switch to pwm_apply_state().55
57
65
67
66
68
Using PWMs with the sysfs interface67
69
-----------------------------------68
70
69
71
If CONFIG_SYSFS is enabled in your kernel configuration a simple sysfs70
72
interface is provided to use the PWMs from userspace. It is exposed at71
73
/sys/class/pwm/. Each probed PWM controller/chip will be exported as72
74
pwmchipN, where N is the base of the PWM chip. Inside the directory you73
75
will find:74
76
75
-
npwm - The number of PWM channels this chip supports (read-only).77
+
npwm78
+
The number of PWM channels this chip supports (read-only).76
79
77
-
export - Exports a PWM channel for use with sysfs (write-only).80
+
export81
+
Exports a PWM channel for use with sysfs (write-only).78
82
79
-
unexport - Unexports a PWM channel from sysfs (write-only).83
+
unexport84
+
Unexports a PWM channel from sysfs (write-only).80
85
81
86
The PWM channels are numbered using a per-chip index from 0 to npwm-1.82
87
83
88
When a PWM channel is exported a pwmX directory will be created in the84
89
pwmchipN directory it is associated with, where X is the number of the85
90
channel that was exported. The following properties will then be available:86
91
87
-
period - The total period of the PWM signal (read/write).88
-
Value is in nanoseconds and is the sum of the active and inactive89
-
time of the PWM.92
+
period93
+
The total period of the PWM signal (read/write).94
+
Value is in nanoseconds and is the sum of the active and inactive95
+
time of the PWM.90
96
91
-
duty_cycle - The active time of the PWM signal (read/write).92
-
Value is in nanoseconds and must be less than the period.97
+
duty_cycle98
+
The active time of the PWM signal (read/write).99
+
Value is in nanoseconds and must be less than the period.93
100
94
-
polarity - Changes the polarity of the PWM signal (read/write).95
-
Writes to this property only work if the PWM chip supports changing96
-
the polarity. The polarity can only be changed if the PWM is not97
-
enabled. Value is the string "normal" or "inversed".101
+
polarity102
+
Changes the polarity of the PWM signal (read/write).103
+
Writes to this property only work if the PWM chip supports changing104
+
the polarity. The polarity can only be changed if the PWM is not105
+
enabled. Value is the string "normal" or "inversed".98
106
99
-
enable - Enable/disable the PWM signal (read/write).100
-
0 - disabled101
-
1 - enabled107
+
enable108
+
Enable/disable the PWM signal (read/write).109
+
110
+
- 0 - disabled111
+
- 1 - enabled102
112
103
113
Implementing a PWM driver104
114
-------------------------105
115
106
116
Currently there are two ways to implement pwm drivers. Traditionally107
117
there only has been the barebone API meaning that each driver has108
118
to implement the pwm_*() functions itself. This means that it's impossible109
119
to have multiple PWM drivers in the system. For this reason it's mandatory110
120
for new drivers to use the generic PWM framework.111
121