summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2016-05-25 10:40:15 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2016-05-25 10:40:15 -0700
commitecc5fbd5ef472a4c659dc56a5739b3f041c0530c (patch)
treeeec1c3ddd6082e6391d7d27ae78d813a8f6c216c /Documentation
parent1f93d2abf488c6a41bdd5e6caf80b559493eea8d (diff)
parent18c588786c08458f5d965d8735ab48f9e51e0b4b (diff)
Merge tag 'pwm/for-4.7-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/thierry.reding/linux-pwm
Pull pwm updates from Thierry Reding: "This set of changes introduces an atomic API to the PWM subsystem. This is influenced by the DRM atomic API that was introduced a while back, though it is obviously a lot simpler. The fundamental idea remains the same, though: drivers provide a single callback to implement the atomic configuration of a PWM channel. As a side-effect the PWM subsystem gains the ability for initial state retrieval, so that the logical state mirrors that of the hardware. Many use-cases don't care about this, but for others it is essential. These new features require changes in all users, which these patches take care of. The core is transitioned to use the atomic callback if available and provides a fallback mechanism for other drivers. Changes to transition users and drivers to the atomic API are postponed to v4.8" * tag 'pwm/for-4.7-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/thierry.reding/linux-pwm: (30 commits) pwm: Add information about polarity, duty cycle and period to debugfs pwm: Switch to the atomic API pwm: Update documentation pwm: Add core infrastructure to allow atomic updates pwm: Add hardware readout infrastructure pwm: Move the enabled/disabled info into pwm_state pwm: Introduce the pwm_state concept pwm: Keep PWM state in sync with hardware state ARM: Explicitly apply PWM config extracted from pwm_args drm: i915: Explicitly apply PWM config extracted from pwm_args input: misc: pwm-beeper: Explicitly apply PWM config extracted from pwm_args input: misc: max8997: Explicitly apply PWM config extracted from pwm_args backlight: lm3630a: explicitly apply PWM config extracted from pwm_args backlight: lp855x: Explicitly apply PWM config extracted from pwm_args backlight: lp8788: Explicitly apply PWM config extracted from pwm_args backlight: pwm_bl: Use pwm_get_args() where appropriate fbdev: ssd1307fb: Use pwm_get_args() where appropriate regulator: pwm: Use pwm_get_args() where appropriate leds: pwm: Use pwm_get_args() where appropriate input: misc: max77693: Use pwm_get_args() where appropriate ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/pwm.txt30
1 files changed, 28 insertions, 2 deletions
diff --git a/Documentation/pwm.txt b/Documentation/pwm.txt
index ca895fd211e4..789b27c6ec99 100644
--- a/Documentation/pwm.txt
+++ b/Documentation/pwm.txt
@@ -42,9 +42,26 @@ variants of these functions, devm_pwm_get() and devm_pwm_put(), also exist.
After being requested, a PWM has to be configured using:
-int pwm_config(struct pwm_device *pwm, int duty_ns, int period_ns);
+int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state);
-To start/stop toggling the PWM output use pwm_enable()/pwm_disable().
+This API controls both the PWM period/duty_cycle config and the
+enable/disable state.
+
+The pwm_config(), pwm_enable() and pwm_disable() functions are just wrappers
+around pwm_apply_state() and should not be used if the user wants to change
+several parameter at once. For example, if you see pwm_config() and
+pwm_{enable,disable}() calls in the same function, this probably means you
+should switch to pwm_apply_state().
+
+The PWM user API also allows one to query the PWM state with pwm_get_state().
+
+In addition to the PWM state, the PWM API also exposes PWM arguments, which
+are the reference PWM config one should use on this PWM.
+PWM arguments are usually platform-specific and allows the PWM user to only
+care about dutycycle relatively to the full period (like, duty = 50% of the
+period). struct pwm_args contains 2 fields (period and polarity) and should
+be used to set the initial PWM config (usually done in the probe function
+of the PWM user). PWM arguments are retrieved with pwm_get_args().
Using PWMs with the sysfs interface
-----------------------------------
@@ -105,6 +122,15 @@ goes low for the remainder of the period. Conversely, a signal with inversed
polarity starts low for the duration of the duty cycle and goes high for the
remainder of the period.
+Drivers are encouraged to implement ->apply() instead of the legacy
+->enable(), ->disable() and ->config() methods. Doing that should provide
+atomicity in the PWM config workflow, which is required when the PWM controls
+a critical device (like a regulator).
+
+The implementation of ->get_state() (a method used to retrieve initial PWM
+state) is also encouraged for the same reason: letting the PWM user know
+about the current PWM state would allow him to avoid glitches.
+
Locking
-------