Documentation/driver-api/pwm.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/pwm.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/pwm.rst
Extension
.rst
Size
7960 bytes
Lines
192
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

======================================
Pulse Width Modulation (PWM) interface
======================================

This provides an overview about the Linux PWM interface

PWMs are commonly used for controlling LEDs, fans or vibrators in
cell phones. PWMs with a fixed purpose have no need implementing
the Linux PWM API (although they could). However, PWMs are often
found as discrete devices on SoCs which have no fixed purpose. It's
up to the board designer to connect them to LEDs or fans. To provide
this kind of flexibility the generic PWM API exists.

Identifying PWMs
----------------

Users of the legacy PWM API use unique IDs to refer to PWM devices.

Instead of referring to a PWM device via its unique ID, board setup code
should instead register a static mapping that can be used to match PWM
consumers to providers, as given in the following example::

	static struct pwm_lookup board_pwm_lookup[] = {
		PWM_LOOKUP("tegra-pwm", 0, "pwm-backlight", NULL,
			   50000, PWM_POLARITY_NORMAL),
	};

	static void __init board_init(void)
	{
		...
		pwm_add_table(board_pwm_lookup, ARRAY_SIZE(board_pwm_lookup));
		...
	}

Using PWMs
----------

Consumers use the pwm_get() function and pass to it the consumer device or a
consumer name. pwm_put() is used to free the PWM device. Managed variants of
the getter, devm_pwm_get() and devm_fwnode_pwm_get(), also exist.

After being requested, a PWM has to be configured using::

	int pwm_apply_might_sleep(struct pwm_device *pwm, struct pwm_state *state);

This API controls both the PWM period/duty_cycle config and the
enable/disable state.

PWM devices can be used from atomic context, if the PWM does not sleep. You
can check if this the case with::

        bool pwm_might_sleep(struct pwm_device *pwm);

If false, the PWM can also be configured from atomic context with::

	int pwm_apply_atomic(struct pwm_device *pwm, struct pwm_state *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
EMI by phase shifting the individual channels of a chip.

The pwm_config(), pwm_enable() and pwm_disable() functions are just wrappers
around pwm_apply_might_sleep() and should not be used if the user wants to change
several parameter at once. For example, if you see pwm_config() and

Annotation

Implementation Notes