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 AC |
42 | device or a consumer name. pwm_put() is used to free the PWM device. Managed |
43 | variants of these functions, devm_pwm_get() and devm_pwm_put(), also exist. | |
8138d2dd | 44 | |
c571123c | 45 | After being requested, a PWM has to be configured using:: |
0c2498f1 | 46 | |
c571123c | 47 | int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state); |
0c2498f1 | 48 | |
a07136fd BB |
49 | This API controls both the PWM period/duty_cycle config and the |
50 | enable/disable state. | |
51 | ||
52 | The pwm_config(), pwm_enable() and pwm_disable() functions are just wrappers | |
53 | around pwm_apply_state() and should not be used if the user wants to change | |
54 | several parameter at once. For example, if you see pwm_config() and | |
55 | pwm_{enable,disable}() calls in the same function, this probably means you | |
56 | should switch to pwm_apply_state(). | |
57 | ||
58 | The PWM user API also allows one to query the PWM state with pwm_get_state(). | |
59 | ||
60 | In addition to the PWM state, the PWM API also exposes PWM arguments, which | |
61 | are the reference PWM config one should use on this PWM. | |
62 | PWM arguments are usually platform-specific and allows the PWM user to only | |
63 | care about dutycycle relatively to the full period (like, duty = 50% of the | |
64 | period). struct pwm_args contains 2 fields (period and polarity) and should | |
65 | be used to set the initial PWM config (usually done in the probe function | |
66 | of the PWM user). PWM arguments are retrieved with pwm_get_args(). | |
0c2498f1 | 67 | |
321a7cea YS |
68 | All consumers should really be reconfiguring the PWM upon resume as |
69 | appropriate. This is the only way to ensure that everything is resumed in | |
70 | the proper order. | |
71 | ||
76abbdde HS |
72 | Using PWMs with the sysfs interface |
73 | ----------------------------------- | |
74 | ||
75 | If CONFIG_SYSFS is enabled in your kernel configuration a simple sysfs | |
76 | interface is provided to use the PWMs from userspace. It is exposed at | |
77 | /sys/class/pwm/. Each probed PWM controller/chip will be exported as | |
78 | pwmchipN, where N is the base of the PWM chip. Inside the directory you | |
79 | will find: | |
80 | ||
c571123c MCC |
81 | npwm |
82 | The number of PWM channels this chip supports (read-only). | |
76abbdde | 83 | |
c571123c MCC |
84 | export |
85 | Exports a PWM channel for use with sysfs (write-only). | |
76abbdde | 86 | |
c571123c MCC |
87 | unexport |
88 | Unexports a PWM channel from sysfs (write-only). | |
76abbdde HS |
89 | |
90 | The PWM channels are numbered using a per-chip index from 0 to npwm-1. | |
91 | ||
92 | When a PWM channel is exported a pwmX directory will be created in the | |
93 | pwmchipN directory it is associated with, where X is the number of the | |
94 | channel that was exported. The following properties will then be available: | |
95 | ||
c571123c MCC |
96 | period |
97 | The total period of the PWM signal (read/write). | |
98 | Value is in nanoseconds and is the sum of the active and inactive | |
99 | time of the PWM. | |
76abbdde | 100 | |
c571123c MCC |
101 | duty_cycle |
102 | The active time of the PWM signal (read/write). | |
103 | Value is in nanoseconds and must be less than the period. | |
76abbdde | 104 | |
c571123c MCC |
105 | polarity |
106 | Changes the polarity of the PWM signal (read/write). | |
107 | Writes to this property only work if the PWM chip supports changing | |
108 | the polarity. The polarity can only be changed if the PWM is not | |
109 | enabled. Value is the string "normal" or "inversed". | |
76abbdde | 110 | |
c571123c MCC |
111 | enable |
112 | Enable/disable the PWM signal (read/write). | |
113 | ||
114 | - 0 - disabled | |
115 | - 1 - enabled | |
76abbdde | 116 | |
0c2498f1 SH |
117 | Implementing a PWM driver |
118 | ------------------------- | |
119 | ||
120 | Currently there are two ways to implement pwm drivers. Traditionally | |
121 | there only has been the barebone API meaning that each driver has | |
122 | to implement the pwm_*() functions itself. This means that it's impossible | |
123 | to have multiple PWM drivers in the system. For this reason it's mandatory | |
124 | for new drivers to use the generic PWM framework. | |
f051c466 TR |
125 | |
126 | A new PWM controller/chip can be added using pwmchip_add() and removed | |
127 | again with pwmchip_remove(). pwmchip_add() takes a filled in struct | |
128 | pwm_chip as argument which provides a description of the PWM chip, the | |
702e304f | 129 | number of PWM devices provided by the chip and the chip-specific |
f051c466 | 130 | implementation of the supported PWM operations to the framework. |
0c2498f1 | 131 | |
3e5314d3 TR |
132 | When implementing polarity support in a PWM driver, make sure to respect the |
133 | signal conventions in the PWM framework. By definition, normal polarity | |
134 | characterizes a signal starts high for the duration of the duty cycle and | |
135 | goes low for the remainder of the period. Conversely, a signal with inversed | |
136 | polarity starts low for the duration of the duty cycle and goes high for the | |
137 | remainder of the period. | |
138 | ||
a07136fd BB |
139 | Drivers are encouraged to implement ->apply() instead of the legacy |
140 | ->enable(), ->disable() and ->config() methods. Doing that should provide | |
141 | atomicity in the PWM config workflow, which is required when the PWM controls | |
142 | a critical device (like a regulator). | |
143 | ||
144 | The implementation of ->get_state() (a method used to retrieve initial PWM | |
145 | state) is also encouraged for the same reason: letting the PWM user know | |
146 | about the current PWM state would allow him to avoid glitches. | |
147 | ||
321a7cea YS |
148 | Drivers should not implement any power management. In other words, |
149 | consumers should implement it as described in the "Using PWMs" section. | |
150 | ||
0c2498f1 SH |
151 | Locking |
152 | ------- | |
153 | ||
154 | The PWM core list manipulations are protected by a mutex, so pwm_request() | |
155 | and pwm_free() may not be called from an atomic context. Currently the | |
156 | PWM core does not enforce any locking to pwm_enable(), pwm_disable() and | |
157 | pwm_config(), so the calling context is currently driver specific. This | |
158 | is an issue derived from the former barebone API and should be fixed soon. | |
159 | ||
160 | Helpers | |
161 | ------- | |
162 | ||
163 | Currently a PWM can only be configured with period_ns and duty_ns. For several | |
164 | use cases freq_hz and duty_percent might be better. Instead of calculating | |
165 | this in your driver please consider adding appropriate helpers to the framework. |