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