Commit | Line | Data |
---|---|---|
0c2498f1 SH |
1 | Pulse Width Modulation (PWM) interface |
2 | ||
3 | This provides an overview about the Linux PWM interface | |
4 | ||
5 | PWMs are commonly used for controlling LEDs, fans or vibrators in | |
6 | cell phones. PWMs with a fixed purpose have no need implementing | |
7 | the Linux PWM API (although they could). However, PWMs are often | |
8 | found as discrete devices on SoCs which have no fixed purpose. It's | |
9 | up to the board designer to connect them to LEDs or fans. To provide | |
10 | this kind of flexibility the generic PWM API exists. | |
11 | ||
12 | Identifying PWMs | |
13 | ---------------- | |
14 | ||
8138d2dd TR |
15 | Users of the legacy PWM API use unique IDs to refer to PWM devices. |
16 | ||
17 | Instead of referring to a PWM device via its unique ID, board setup code | |
18 | should instead register a static mapping that can be used to match PWM | |
19 | consumers to providers, as given in the following example: | |
20 | ||
21 | static struct pwm_lookup board_pwm_lookup[] = { | |
42844029 AB |
22 | PWM_LOOKUP("tegra-pwm", 0, "pwm-backlight", NULL, |
23 | 50000, PWM_POLARITY_NORMAL), | |
8138d2dd TR |
24 | }; |
25 | ||
26 | static void __init board_init(void) | |
27 | { | |
28 | ... | |
29 | pwm_add_table(board_pwm_lookup, ARRAY_SIZE(board_pwm_lookup)); | |
30 | ... | |
31 | } | |
0c2498f1 SH |
32 | |
33 | Using PWMs | |
34 | ---------- | |
35 | ||
8138d2dd TR |
36 | Legacy users can request a PWM device using pwm_request() and free it |
37 | after usage with pwm_free(). | |
38 | ||
39 | New users should use the pwm_get() function and pass to it the consumer | |
6354316d AC |
40 | device or a consumer name. pwm_put() is used to free the PWM device. Managed |
41 | variants of these functions, devm_pwm_get() and devm_pwm_put(), also exist. | |
8138d2dd | 42 | |
702e304f | 43 | After being requested, a PWM has to be configured using: |
0c2498f1 SH |
44 | |
45 | int pwm_config(struct pwm_device *pwm, int duty_ns, int period_ns); | |
46 | ||
47 | To start/stop toggling the PWM output use pwm_enable()/pwm_disable(). | |
48 | ||
76abbdde HS |
49 | Using PWMs with the sysfs interface |
50 | ----------------------------------- | |
51 | ||
52 | If CONFIG_SYSFS is enabled in your kernel configuration a simple sysfs | |
53 | interface is provided to use the PWMs from userspace. It is exposed at | |
54 | /sys/class/pwm/. Each probed PWM controller/chip will be exported as | |
55 | pwmchipN, where N is the base of the PWM chip. Inside the directory you | |
56 | will find: | |
57 | ||
58 | npwm - The number of PWM channels this chip supports (read-only). | |
59 | ||
60 | export - Exports a PWM channel for use with sysfs (write-only). | |
61 | ||
62 | unexport - Unexports a PWM channel from sysfs (write-only). | |
63 | ||
64 | The PWM channels are numbered using a per-chip index from 0 to npwm-1. | |
65 | ||
66 | When a PWM channel is exported a pwmX directory will be created in the | |
67 | pwmchipN directory it is associated with, where X is the number of the | |
68 | channel that was exported. The following properties will then be available: | |
69 | ||
70 | period - The total period of the PWM signal (read/write). | |
71 | Value is in nanoseconds and is the sum of the active and inactive | |
72 | time of the PWM. | |
73 | ||
74 | duty_cycle - The active time of the PWM signal (read/write). | |
75 | Value is in nanoseconds and must be less than the period. | |
76 | ||
77 | polarity - Changes the polarity of the PWM signal (read/write). | |
78 | Writes to this property only work if the PWM chip supports changing | |
79 | the polarity. The polarity can only be changed if the PWM is not | |
80 | enabled. Value is the string "normal" or "inversed". | |
81 | ||
82 | enable - Enable/disable the PWM signal (read/write). | |
83 | 0 - disabled | |
84 | 1 - enabled | |
85 | ||
0c2498f1 SH |
86 | Implementing a PWM driver |
87 | ------------------------- | |
88 | ||
89 | Currently there are two ways to implement pwm drivers. Traditionally | |
90 | there only has been the barebone API meaning that each driver has | |
91 | to implement the pwm_*() functions itself. This means that it's impossible | |
92 | to have multiple PWM drivers in the system. For this reason it's mandatory | |
93 | for new drivers to use the generic PWM framework. | |
f051c466 TR |
94 | |
95 | A new PWM controller/chip can be added using pwmchip_add() and removed | |
96 | again with pwmchip_remove(). pwmchip_add() takes a filled in struct | |
97 | pwm_chip as argument which provides a description of the PWM chip, the | |
702e304f | 98 | number of PWM devices provided by the chip and the chip-specific |
f051c466 | 99 | implementation of the supported PWM operations to the framework. |
0c2498f1 | 100 | |
3e5314d3 TR |
101 | When implementing polarity support in a PWM driver, make sure to respect the |
102 | signal conventions in the PWM framework. By definition, normal polarity | |
103 | characterizes a signal starts high for the duration of the duty cycle and | |
104 | goes low for the remainder of the period. Conversely, a signal with inversed | |
105 | polarity starts low for the duration of the duty cycle and goes high for the | |
106 | remainder of the period. | |
107 | ||
0c2498f1 SH |
108 | Locking |
109 | ------- | |
110 | ||
111 | The PWM core list manipulations are protected by a mutex, so pwm_request() | |
112 | and pwm_free() may not be called from an atomic context. Currently the | |
113 | PWM core does not enforce any locking to pwm_enable(), pwm_disable() and | |
114 | pwm_config(), so the calling context is currently driver specific. This | |
115 | is an issue derived from the former barebone API and should be fixed soon. | |
116 | ||
117 | Helpers | |
118 | ------- | |
119 | ||
120 | Currently a PWM can only be configured with period_ns and duty_ns. For several | |
121 | use cases freq_hz and duty_percent might be better. Instead of calculating | |
122 | this in your driver please consider adding appropriate helpers to the framework. |