tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
pwm: Update documentation
Update the PWM subsystem documentation to reflect the atomic PWM
changes.
Signed-off-by: Boris Brezillon <boris.brezillon@free-electrons.com>
Signed-off-by: Thierry Reding <thierry.reding@gmail.com>
authored by
Boris Brezillon
and committed by
Thierry Reding
a07136fd
5ec803ed
+28
-2
+28
-2
Documentation/pwm.txt
+28
-2
Documentation/pwm.txt
···
42
42
43
43
After being requested, a PWM has to be configured using:
44
44
45
-
int pwm_config(struct pwm_device *pwm, int duty_ns, int period_ns);
45
+
int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state);
46
46
47
-
To start/stop toggling the PWM output use pwm_enable()/pwm_disable().
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().
48
65
49
66
Using PWMs with the sysfs interface
50
67
-----------------------------------
···
121
104
goes low for the remainder of the period. Conversely, a signal with inversed
122
105
polarity starts low for the duration of the duty cycle and goes high for the
123
106
remainder of the period.
107
+
108
+
Drivers are encouraged to implement ->apply() instead of the legacy
109
+
->enable(), ->disable() and ->config() methods. Doing that should provide
110
+
atomicity in the PWM config workflow, which is required when the PWM controls
111
+
a critical device (like a regulator).
112
+
113
+
The implementation of ->get_state() (a method used to retrieve initial PWM
114
+
state) is also encouraged for the same reason: letting the PWM user know
115
+
about the current PWM state would allow him to avoid glitches.
124
116
125
117
Locking
126
118
-------