[PATCH] docs: pwm: Adapt Locking paragraph to reality

[PATCH] docs: pwm: Adapt Locking paragraph to reality

[Uwe Kleine-König]

We have the distinction between pwm_apply_atomic() and
pwm_apply_might_sleep() since commit c748a6d77c06 (pwm: Rename
pwm_apply_state() to pwm_apply_might_sleep()) contained in v6.8-rc1.

Locking in the core was introduced in commit 1cc2e1faafb3 ("pwm: Add
more locking", contained in v6.13-rc1) to serialize per-chip callbacks
and device removal.

Signed-off-by: Uwe Kleine-König <u.kleine-koenig@baylibre.com>
---
Hello,

I guess there are no objections and so will apply this patch to my pwm
tree in a week or so if there is no negative feedback.

Best regards
Uwe

 Documentation/driver-api/pwm.rst | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst
index b41b1c56477f..0d27a40f5818 100644
--- a/Documentation/driver-api/pwm.rst
+++ b/Documentation/driver-api/pwm.rst
@@ -173,10 +173,15 @@ Locking
 -------
 
 The PWM core list manipulations are protected by a mutex, so pwm_get()
-and pwm_put() may not be called from an atomic context. Currently the
-PWM core does not enforce any locking to pwm_enable(), pwm_disable() and
-pwm_config(), so the calling context is currently driver specific. This
-is an issue derived from the former barebone API and should be fixed soon.
+and pwm_put() may not be called from an atomic context.
+Most functions in the PWM consumer API might sleep and so must not be called
+from atomic context. The notable exception is pwm_apply_atomic() which has the
+same semantics as pwm_apply_might_sleep() but can be called from atomic context.
+(The price for that is that it doesn't work for all PWM devices, use
+pwm_might_sleep() to check if a given PWM supports atomic operation.
+
+Locking in the PWM core ensures that callbacks related to a single chip are
+serialized.
 
 Helpers
 -------

base-commit: f817b6dd2b62d921a6cdc0a3ac599cd1851f343c
-- 
2.49.0

Re: [PATCH] docs: pwm: Adapt Locking paragraph to reality

[Uwe Kleine-König]

[-- Attachment #1: Type: text/plain, Size: 798 bytes --]

Hello,

On Tue, Jun 24, 2025 at 12:05:00PM +0200, Uwe Kleine-König wrote:
> We have the distinction between pwm_apply_atomic() and
> pwm_apply_might_sleep() since commit c748a6d77c06 (pwm: Rename
> pwm_apply_state() to pwm_apply_might_sleep()) contained in v6.8-rc1.
> 
> Locking in the core was introduced in commit 1cc2e1faafb3 ("pwm: Add
> more locking", contained in v6.13-rc1) to serialize per-chip callbacks
> and device removal.
> 
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@baylibre.com>
> ---
> I guess there are no objections and so will apply this patch to my pwm
> tree in a week or so if there is no negative feedback.

I did that now. You can find it at
https://git.kernel.org/pub/scm/linux/kernel/git/ukleinek/linux.git pwm/for-next
.

Best regards
Uwe

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]