[PATCH] pwm: Document that the pinstate of a disabled PWM isn't reliable

[PATCH] pwm: Document that the pinstate of a disabled PWM isn't reliable

[Uwe Kleine-König]

Some (most?) drivers emit the inactive state when the PWM is disabled.
However there are exceptions, so document that a consumer better doesn't
depend on this behaviour.

Some known exceptions:

  - imx27 emits 0 independent of the configured polarity
  - mxs just drives the output to the last emitted state.
  - iqs620a makes the output tristated on disable, so an external
    pull-down would be required.

Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
 Documentation/driver-api/pwm.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst
index ccb06e485756..fd26c3d895b6 100644
--- a/Documentation/driver-api/pwm.rst
+++ b/Documentation/driver-api/pwm.rst
@@ -49,6 +49,12 @@ After being requested, a PWM has to be configured using::
 
 This API controls both the PWM period/duty_cycle config and the
 enable/disable state.
+
+As a consumer, don't rely on the output's state for a disabled PWM. If it's
+easily possible, drivers are supposed to emit the inactive state, but some
+drivers cannot. If you rely on getting the inactive state, use .duty_cycle=0,
+.enabled=true.
+
 There is also a usage_power setting: If set, the PWM driver is only required to
 maintain the power output but has more freedom regarding signal form.
 If supported by the driver, the signal can be optimized, for example to improve
-- 
2.35.1

Re: (EXT) [PATCH] pwm: Document that the pinstate of a disabled PWM isn't reliable

[Alexander Stein]

Am Dienstag, 17. Mai 2022, 17:05:55 CEST schrieb Uwe Kleine-König:
> Some (most?) drivers emit the inactive state when the PWM is disabled.
> However there are exceptions, so document that a consumer better doesn't
> depend on this behaviour.
> 
> Some known exceptions:
> 
>   - imx27 emits 0 independent of the configured polarity
>   - mxs just drives the output to the last emitted state.
>   - iqs620a makes the output tristated on disable, so an external
>     pull-down would be required.
> 
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> ---
>  Documentation/driver-api/pwm.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/driver-api/pwm.rst
> b/Documentation/driver-api/pwm.rst index ccb06e485756..fd26c3d895b6 100644
> --- a/Documentation/driver-api/pwm.rst
> +++ b/Documentation/driver-api/pwm.rst
> @@ -49,6 +49,12 @@ After being requested, a PWM has to be configured using::
> 
>  This API controls both the PWM period/duty_cycle config and the
>  enable/disable state.
> +
> +As a consumer, don't rely on the output's state for a disabled PWM. If it's
> +easily possible, drivers are supposed to emit the inactive state, but some
> +drivers cannot. If you rely on getting the inactive state, use
> .duty_cycle=0, +.enabled=true.
> +
>  There is also a usage_power setting: If set, the PWM driver is only
> required to maintain the power output but has more freedom regarding signal
> form. If supported by the driver, the signal can be optimized, for example
> to improve

Acked-by: Alexander Stein <alexander.stein@ew.tq-group.com>