]>
Commit | Line | Data |
---|---|---|
c571123c | 1 | ====================================== |
0c2498f1 | 2 | Pulse Width Modulation (PWM) interface |
c571123c | 3 | ====================================== |
0c2498f1 SH |
4 | |
5 | This provides an overview about the Linux PWM interface | |
6 | ||
7 | PWMs are commonly used for controlling LEDs, fans or vibrators in | |
8 | cell phones. PWMs with a fixed purpose have no need implementing | |
9 | the Linux PWM API (although they could). However, PWMs are often | |
10 | found as discrete devices on SoCs which have no fixed purpose. It's | |
11 | up to the board designer to connect them to LEDs or fans. To provide | |
12 | this kind of flexibility the generic PWM API exists. | |
13 | ||
14 | Identifying PWMs | |
15 | ---------------- | |
16 | ||
8138d2dd TR |
17 | Users of the legacy PWM API use unique IDs to refer to PWM devices. |
18 | ||
19 | Instead of referring to a PWM device via its unique ID, board setup code | |
20 | should instead register a static mapping that can be used to match PWM | |
c571123c | 21 | consumers to providers, as given in the following example:: |
8138d2dd TR |
22 | |
23 | static struct pwm_lookup board_pwm_lookup[] = { | |
42844029 AB |
24 | PWM_LOOKUP("tegra-pwm", 0, "pwm-backlight", NULL, |
25 | 50000, PWM_POLARITY_NORMAL), | |
8138d2dd TR |
26 | }; |
27 | ||
28 | static void __init board_init(void) | |
29 | { | |
30 | ... | |
31 | pwm_add_table(board_pwm_lookup, ARRAY_SIZE(board_pwm_lookup)); | |
32 | ... | |
33 | } | |
0c2498f1 SH |
34 | |
35 | Using PWMs | |
36 | ---------- | |
37 | ||
8138d2dd TR |
38 | Legacy users can request a PWM device using pwm_request() and free it |
39 | after usage with pwm_free(). | |
40 | ||
41 | New users should use the pwm_get() function and pass to it the consumer | |
6354316d | 42 | device or a consumer name. pwm_put() is used to free the PWM device. Managed |
c333b936 AS |
43 | variants of the getter, devm_pwm_get(), devm_of_pwm_get(), |
44 | devm_fwnode_pwm_get(), also exist. | |
8138d2dd | 45 | |
c571123c | 46 | After being requested, a PWM has to be configured using:: |
0c2498f1 | 47 | |
c571123c | 48 | int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state); |
0c2498f1 | 49 | |
a07136fd BB |
50 | This API controls both the PWM period/duty_cycle config and the |
51 | enable/disable state. | |
80a22fde UKK |
52 | |
53 | As a consumer, don't rely on the output's state for a disabled PWM. If it's | |
54 | easily possible, drivers are supposed to emit the inactive state, but some | |
55 | drivers cannot. If you rely on getting the inactive state, use .duty_cycle=0, | |
56 | .enabled=true. | |
57 | ||
9e40ee18 CG |
58 | There is also a usage_power setting: If set, the PWM driver is only required to |
59 | maintain the power output but has more freedom regarding signal form. | |
60 | If supported by the driver, the signal can be optimized, for example to improve | |
61 | EMI by phase shifting the individual channels of a chip. | |
a07136fd BB |
62 | |
63 | The pwm_config(), pwm_enable() and pwm_disable() functions are just wrappers | |
64 | around pwm_apply_state() and should not be used if the user wants to change | |
65 | several parameter at once. For example, if you see pwm_config() and | |
66 | pwm_{enable,disable}() calls in the same function, this probably means you | |
67 | should switch to pwm_apply_state(). | |
68 | ||
a6efb350 UKK |
69 | The PWM user API also allows one to query the PWM state that was passed to the |
70 | last invocation of pwm_apply_state() using pwm_get_state(). Note this is | |
71 | different to what the driver has actually implemented if the request cannot be | |
72 | satisfied exactly with the hardware in use. There is currently no way for | |
73 | consumers to get the actually implemented settings. | |
a07136fd BB |
74 | |
75 | In addition to the PWM state, the PWM API also exposes PWM arguments, which | |
76 | are the reference PWM config one should use on this PWM. | |
77 | PWM arguments are usually platform-specific and allows the PWM user to only | |
78 | care about dutycycle relatively to the full period (like, duty = 50% of the | |
79 | period). struct pwm_args contains 2 fields (period and polarity) and should | |
80 | be used to set the initial PWM config (usually done in the probe function | |
81 | of the PWM user). PWM arguments are retrieved with pwm_get_args(). | |
0c2498f1 | 82 | |
321a7cea YS |
83 | All consumers should really be reconfiguring the PWM upon resume as |
84 | appropriate. This is the only way to ensure that everything is resumed in | |
85 | the proper order. | |
86 | ||
76abbdde HS |
87 | Using PWMs with the sysfs interface |
88 | ----------------------------------- | |
89 | ||
90 | If CONFIG_SYSFS is enabled in your kernel configuration a simple sysfs | |
91 | interface is provided to use the PWMs from userspace. It is exposed at | |
92 | /sys/class/pwm/. Each probed PWM controller/chip will be exported as | |
93 | pwmchipN, where N is the base of the PWM chip. Inside the directory you | |
94 | will find: | |
95 | ||
c571123c MCC |
96 | npwm |
97 | The number of PWM channels this chip supports (read-only). | |
76abbdde | 98 | |
c571123c MCC |
99 | export |
100 | Exports a PWM channel for use with sysfs (write-only). | |
76abbdde | 101 | |
c571123c MCC |
102 | unexport |
103 | Unexports a PWM channel from sysfs (write-only). | |
76abbdde HS |
104 | |
105 | The PWM channels are numbered using a per-chip index from 0 to npwm-1. | |
106 | ||
107 | When a PWM channel is exported a pwmX directory will be created in the | |
108 | pwmchipN directory it is associated with, where X is the number of the | |
109 | channel that was exported. The following properties will then be available: | |
110 | ||
c571123c MCC |
111 | period |
112 | The total period of the PWM signal (read/write). | |
113 | Value is in nanoseconds and is the sum of the active and inactive | |
114 | time of the PWM. | |
76abbdde | 115 | |
c571123c MCC |
116 | duty_cycle |
117 | The active time of the PWM signal (read/write). | |
118 | Value is in nanoseconds and must be less than the period. | |
76abbdde | 119 | |
c571123c MCC |
120 | polarity |
121 | Changes the polarity of the PWM signal (read/write). | |
122 | Writes to this property only work if the PWM chip supports changing | |
123 | the polarity. The polarity can only be changed if the PWM is not | |
124 | enabled. Value is the string "normal" or "inversed". | |
76abbdde | 125 | |
c571123c MCC |
126 | enable |
127 | Enable/disable the PWM signal (read/write). | |
128 | ||
129 | - 0 - disabled | |
130 | - 1 - enabled | |
76abbdde | 131 | |
0c2498f1 SH |
132 | Implementing a PWM driver |
133 | ------------------------- | |
134 | ||
135 | Currently there are two ways to implement pwm drivers. Traditionally | |
136 | there only has been the barebone API meaning that each driver has | |
137 | to implement the pwm_*() functions itself. This means that it's impossible | |
138 | to have multiple PWM drivers in the system. For this reason it's mandatory | |
139 | for new drivers to use the generic PWM framework. | |
f051c466 TR |
140 | |
141 | A new PWM controller/chip can be added using pwmchip_add() and removed | |
142 | again with pwmchip_remove(). pwmchip_add() takes a filled in struct | |
143 | pwm_chip as argument which provides a description of the PWM chip, the | |
702e304f | 144 | number of PWM devices provided by the chip and the chip-specific |
f051c466 | 145 | implementation of the supported PWM operations to the framework. |
0c2498f1 | 146 | |
3e5314d3 TR |
147 | When implementing polarity support in a PWM driver, make sure to respect the |
148 | signal conventions in the PWM framework. By definition, normal polarity | |
149 | characterizes a signal starts high for the duration of the duty cycle and | |
150 | goes low for the remainder of the period. Conversely, a signal with inversed | |
151 | polarity starts low for the duration of the duty cycle and goes high for the | |
152 | remainder of the period. | |
153 | ||
a07136fd BB |
154 | Drivers are encouraged to implement ->apply() instead of the legacy |
155 | ->enable(), ->disable() and ->config() methods. Doing that should provide | |
156 | atomicity in the PWM config workflow, which is required when the PWM controls | |
157 | a critical device (like a regulator). | |
158 | ||
159 | The implementation of ->get_state() (a method used to retrieve initial PWM | |
160 | state) is also encouraged for the same reason: letting the PWM user know | |
161 | about the current PWM state would allow him to avoid glitches. | |
162 | ||
321a7cea YS |
163 | Drivers should not implement any power management. In other words, |
164 | consumers should implement it as described in the "Using PWMs" section. | |
165 | ||
0c2498f1 SH |
166 | Locking |
167 | ------- | |
168 | ||
169 | The PWM core list manipulations are protected by a mutex, so pwm_request() | |
170 | and pwm_free() may not be called from an atomic context. Currently the | |
171 | PWM core does not enforce any locking to pwm_enable(), pwm_disable() and | |
172 | pwm_config(), so the calling context is currently driver specific. This | |
173 | is an issue derived from the former barebone API and should be fixed soon. | |
174 | ||
175 | Helpers | |
176 | ------- | |
177 | ||
178 | Currently a PWM can only be configured with period_ns and duty_ns. For several | |
179 | use cases freq_hz and duty_percent might be better. Instead of calculating | |
180 | this in your driver please consider adding appropriate helpers to the framework. |