| Sascha Hauer | 0c2498f | 2011-01-28 09:40:40 +0100 | [diff] [blame] | 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 | |
| 15 | Users of the legacy PWM API use unique IDs to refer to PWM devices. One |
| 16 | goal of the new PWM framework is to get rid of this global namespace. |
| 17 | |
| 18 | Using PWMs |
| 19 | ---------- |
| 20 | |
| 21 | A PWM can be requested using pwm_request() and freed after usage with |
| 22 | pwm_free(). After being requested a PWM has to be configured using |
| 23 | |
| 24 | int pwm_config(struct pwm_device *pwm, int duty_ns, int period_ns); |
| 25 | |
| 26 | To start/stop toggling the PWM output use pwm_enable()/pwm_disable(). |
| 27 | |
| 28 | Implementing a PWM driver |
| 29 | ------------------------- |
| 30 | |
| 31 | Currently there are two ways to implement pwm drivers. Traditionally |
| 32 | there only has been the barebone API meaning that each driver has |
| 33 | to implement the pwm_*() functions itself. This means that it's impossible |
| 34 | to have multiple PWM drivers in the system. For this reason it's mandatory |
| 35 | for new drivers to use the generic PWM framework. |
| Thierry Reding | f051c46 | 2011-12-14 11:12:23 +0100 | [diff] [blame^] | 36 | |
| 37 | A new PWM controller/chip can be added using pwmchip_add() and removed |
| 38 | again with pwmchip_remove(). pwmchip_add() takes a filled in struct |
| 39 | pwm_chip as argument which provides a description of the PWM chip, the |
| 40 | number of PWM devices provider by the chip and the chip-specific |
| 41 | implementation of the supported PWM operations to the framework. |
| Sascha Hauer | 0c2498f | 2011-01-28 09:40:40 +0100 | [diff] [blame] | 42 | |
| 43 | Locking |
| 44 | ------- |
| 45 | |
| 46 | The PWM core list manipulations are protected by a mutex, so pwm_request() |
| 47 | and pwm_free() may not be called from an atomic context. Currently the |
| 48 | PWM core does not enforce any locking to pwm_enable(), pwm_disable() and |
| 49 | pwm_config(), so the calling context is currently driver specific. This |
| 50 | is an issue derived from the former barebone API and should be fixed soon. |
| 51 | |
| 52 | Helpers |
| 53 | ------- |
| 54 | |
| 55 | Currently a PWM can only be configured with period_ns and duty_ns. For several |
| 56 | use cases freq_hz and duty_percent might be better. Instead of calculating |
| 57 | this in your driver please consider adding appropriate helpers to the framework. |