projects / linux.git / blame
| Commit | Line | Data |
|---|---|---|
| 0c2498f1 SH |
1 | Pulse Width Modulation (PWM) interface |
| 2 | ||
| 3 | This provides an overview about the Linux PWM interface | |
| 4 | ||
| 5 | PWMs are commonly used for controlling LEDs, fans or vibrators in | |
| 6 | cell phones. PWMs with a fixed purpose have no need implementing | |
| 7 | the Linux PWM API (although they could). However, PWMs are often | |
| 8 | found as discrete devices on SoCs which have no fixed purpose. It's | |
| 9 | up to the board designer to connect them to LEDs or fans. To provide | |
| 10 | this kind of flexibility the generic PWM API exists. | |
| 11 | ||
| 12 | Identifying PWMs | |
| 13 | ---------------- | |
| 14 | ||
| 8138d2dd TR |
15 | Users of the legacy PWM API use unique IDs to refer to PWM devices. |
| 16 | ||
| 17 | Instead of referring to a PWM device via its unique ID, board setup code | |
| 18 | should instead register a static mapping that can be used to match PWM | |
| 19 | consumers to providers, as given in the following example: | |
| 20 | ||
| 21 | static struct pwm_lookup board_pwm_lookup[] = { | |
| 22 | PWM_LOOKUP("tegra-pwm", 0, "pwm-backlight", NULL), | |
| 23 | }; | |
| 24 | ||
| 25 | static void __init board_init(void) | |
| 26 | { | |
| 27 | ... | |
| 28 | pwm_add_table(board_pwm_lookup, ARRAY_SIZE(board_pwm_lookup)); | |
| 29 | ... | |
| 30 | } | |
| 0c2498f1 SH |
31 | |
| 32 | Using PWMs | |
| 33 | ---------- | |
| 34 | ||
| 8138d2dd TR |
35 | Legacy users can request a PWM device using pwm_request() and free it |
| 36 | after usage with pwm_free(). | |
| 37 | ||
| 38 | New users should use the pwm_get() function and pass to it the consumer | |
| 6354316d AC |
39 | device or a consumer name. pwm_put() is used to free the PWM device. Managed |
| 40 | variants of these functions, devm_pwm_get() and devm_pwm_put(), also exist. | |
| 8138d2dd TR |
41 | |
| 42 | After being requested a PWM has to be configured using: | |
| 0c2498f1 SH |
43 | |
| 44 | int pwm_config(struct pwm_device *pwm, int duty_ns, int period_ns); | |
| 45 | ||
| 46 | To start/stop toggling the PWM output use pwm_enable()/pwm_disable(). | |
| 47 | ||
| 48 | Implementing a PWM driver | |
| 49 | ------------------------- | |
| 50 | ||
| 51 | Currently there are two ways to implement pwm drivers. Traditionally | |
| 52 | there only has been the barebone API meaning that each driver has | |
| 53 | to implement the pwm_*() functions itself. This means that it's impossible | |
| 54 | to have multiple PWM drivers in the system. For this reason it's mandatory | |
| 55 | for new drivers to use the generic PWM framework. | |
| f051c466 TR |
56 | |
| 57 | A new PWM controller/chip can be added using pwmchip_add() and removed | |
| 58 | again with pwmchip_remove(). pwmchip_add() takes a filled in struct | |
| 59 | pwm_chip as argument which provides a description of the PWM chip, the | |
| 60 | number of PWM devices provider by the chip and the chip-specific | |
| 61 | implementation of the supported PWM operations to the framework. | |
| 0c2498f1 SH |
62 | |
| 63 | Locking | |
| 64 | ------- | |
| 65 | ||
| 66 | The PWM core list manipulations are protected by a mutex, so pwm_request() | |
| 67 | and pwm_free() may not be called from an atomic context. Currently the | |
| 68 | PWM core does not enforce any locking to pwm_enable(), pwm_disable() and | |
| 69 | pwm_config(), so the calling context is currently driver specific. This | |
| 70 | is an issue derived from the former barebone API and should be fixed soon. | |
| 71 | ||
| 72 | Helpers | |
| 73 | ------- | |
| 74 | ||
| 75 | Currently a PWM can only be configured with period_ns and duty_ns. For several | |
| 76 | use cases freq_hz and duty_percent might be better. Instead of calculating | |
| 77 | this in your driver please consider adding appropriate helpers to the framework. |