| 1 | Generic PWM Device API |
| 2 | |
| 3 | February 1, 2010 |
| 4 | Bill Gatliff |
| 5 | <bgat@billgatliff.com> |
| 6 | |
| 7 | |
| 8 | |
| 9 | The code in drivers/pwm and include/linux/pwm/ implements an API for |
| 10 | applications involving pulse-width-modulation signals. This document |
| 11 | describes how the API implementation facilitates both PWM-generating |
| 12 | devices, and users of those devices. |
| 13 | |
| 14 | |
| 15 | |
| 16 | Motivation |
| 17 | |
| 18 | The primary goals for implementing the "generic PWM API" are to |
| 19 | consolidate the various PWM implementations within a consistent and |
| 20 | redundancy-reducing framework, and to facilitate the use of |
| 21 | hotpluggable PWM devices. |
| 22 | |
| 23 | Previous PWM-related implementations within the Linux kernel achieved |
| 24 | their consistency via cut-and-paste, but did not need to (and didn't) |
| 25 | facilitate more than one PWM-generating device within the system--- |
| 26 | hotplug or otherwise. The Generic PWM Device API might be most |
| 27 | appropriately viewed as an update to those implementations, rather |
| 28 | than a complete rewrite. |
| 29 | |
| 30 | |
| 31 | |
| 32 | Challenges |
| 33 | |
| 34 | One of the difficulties in implementing a generic PWM framework is the |
| 35 | fact that pulse-width-modulation applications involve real-world |
| 36 | signals, which often must be carefully managed to prevent destruction |
| 37 | of hardware that is linked to those signals. A DC motor that |
| 38 | experiences a brief interruption in the PWM signal controlling it |
| 39 | might destructively overheat; it could suddenly change speed, losing |
| 40 | synchronization with a sensor; it could even suddenly change direction |
| 41 | or torque, breaking the mechanical device connected to it. |
| 42 | |
| 43 | (A generic PWM device framework is not directly responsible for |
| 44 | preventing the above scenarios: that responsibility lies with the |
| 45 | hardware designer, and the application and driver authors. But it |
| 46 | must to the greatest extent possible make it easy to avoid such |
| 47 | problems). |
| 48 | |
| 49 | A generic PWM device framework must accommodate the substantial |
| 50 | differences between available PWM-generating hardware devices, without |
| 51 | becoming sub-optimal for any of them. |
| 52 | |
| 53 | Finally, a generic PWM device framework must be relatively |
| 54 | lightweight, computationally speaking. Some PWM users demand |
| 55 | high-speed outputs, plus the ability to regulate those outputs |
| 56 | quickly. A device framework must be able to "keep up" with such |
| 57 | hardware, while still leaving time to do real work. |
| 58 | |
| 59 | The Generic PWM Device API is an attempt to meet all of the above |
| 60 | requirements. At its initial publication, the API was already in use |
| 61 | managing small DC motors, sensors and solenoids through a |
| 62 | custom-designed, optically-isolated H-bridge driver. |
| 63 | |
| 64 | |
| 65 | |
| 66 | Functional Overview |
| 67 | |
| 68 | The Generic PWM Device API framework is implemented in |
| 69 | include/linux/pwm/pwm.h and drivers/pwm/pwm.c. The functions therein |
| 70 | use information from pwm_device, pwm_channel and pwm_channel_config |
| 71 | structures to invoke services in PWM peripheral device drivers. |
| 72 | Consult drivers/pwm/atmel-pwm.c for an example driver. |
| 73 | |
| 74 | There are two classes of adopters of the PWM framework: |
| 75 | |
| 76 | "Users" -- those wishing to employ the API merely to produce PWM |
| 77 | signals; once they have identified the appropriate physical output |
| 78 | on the platform in question, they don't care about the details of |
| 79 | the underlying hardware |
| 80 | |
| 81 | "Driver authors" -- those wishing to bind devices that can generate |
| 82 | PWM signals to the Generic PWM Device API, so that the services of |
| 83 | those devices become available to users. Assuming the hardware can |
| 84 | support the needs of a user, driver authors don't care about the |
| 85 | details of the user's application |
| 86 | |
| 87 | Generally speaking, users will first invoke pwm_request() to obtain a |
| 88 | handle to a PWM device. They will then pass that handle to functions |
| 89 | like pwm_duty_ns() and pwm_period_ns() to set the duty cycle and |
| 90 | period of the PWM signal, respectively. They will also invoke |
| 91 | pwm_start() and pwm_stop() to turn the signal on and off. |
| 92 | |
| 93 | The Generic PWM API framework also provides a sysfs interface to PWM |
| 94 | devices, which is adequate for basic application needs and testing. |
| 95 | |
| 96 | Driver authors fill out a pwm_device structure, which describes the |
| 97 | capabilities of the PWM hardware being constructed--- including the |
| 98 | number of distinct output "channels" the peripheral offers. They then |
| 99 | invoke pwm_register() (usually from within their device's probe() |
| 100 | handler) to make the PWM API aware of their device. The framework |
| 101 | will call back to the methods described in the pwm_device structure as |
| 102 | users begin to configure and utilize the hardware. |
| 103 | |
| 104 | Note that PWM signals can be produced by a variety of peripherals, |
| 105 | beyond the true "PWM hardware" offered by many system-on-chip devices. |
| 106 | Other possibilities include timer/counters with compare-match |
| 107 | capabilities, carefully-programmed synchronous serial ports |
| 108 | (e.g. SPI), and GPIO pins driven by kernel interval timers. With a |
| 109 | proper pwm_device structure, these devices and pseudo-devices can all |
| 110 | be accommodated by the Generic PWM Device API framework. |
| 111 | |
| 112 | |
| 113 | |
| 114 | Using the API to Generate PWM Signals -- Basic Functions for Users |
| 115 | |
| 116 | |
| 117 | pwm_request() -- Returns a pwm_channel pointer, which is subsequently |
| 118 | passed to the other user-related PWM functions. Once requested, a PWM |
| 119 | channel is marked as in-use and subsequent requests prior to |
| 120 | pwm_free() will fail. |
| 121 | |
| 122 | The names used to refer to PWM devices are defined by driver authors. |
| 123 | Typically they are platform device bus identifiers, and this |
| 124 | convention is encouraged for consistency. |
| 125 | |
| 126 | |
| 127 | pwm_free() -- Marks a PWM channel as no longer in use. The PWM device |
| 128 | is stopped before it is released by the API. |
| 129 | |
| 130 | |
| 131 | pwm_period_ns() -- Specifies the PWM signal's period, in nanoseconds. |
| 132 | |
| 133 | |
| 134 | pwm_duty_ns() -- Specifies the PWM signal's active duration, in nanoseconds. |
| 135 | |
| 136 | |
| 137 | pwm_duty_percent() -- Specifies the PWM signal's active duration, as a |
| 138 | percentage of the current period of the signal. NOTE: this value is |
| 139 | not recalculated if the period of the signal is subsequently changed. |
| 140 | |
| 141 | |
| 142 | pwm_start(), pwm_stop() -- Turns the PWM signal on and off. Except |
| 143 | where stated otherwise by a driver author, signals are stopped at the |
| 144 | end of the current period, at which time the output is set to its |
| 145 | inactive state. |
| 146 | |
| 147 | |
| 148 | pwm_polarity() -- Defines whether the PWM signal output's active |
| 149 | region is "1" or "0". A 10% duty-cycle, polarity=1 signal will |
| 150 | conventionally be at 5V (or 3.3V, or 1000V, or whatever the platform |
| 151 | hardware does) for 10% of the period. The same configuration of a |
| 152 | polarity=0 signal will be at 5V (or 3.3V, or ...) for 90% of the |
| 153 | period. |
| 154 | |
| 155 | |
| 156 | |
| 157 | Using the API to Generate PWM Signals -- Advanced Functions |
| 158 | |
| 159 | |
| 160 | pwm_config() -- Passes a pwm_channel_config structure to the |
| 161 | associated device driver. This function is invoked by pwm_start(), |
| 162 | pwm_duty_ns(), etc. and is one of two main entry points to the PWM |
| 163 | driver for the hardware being used. The configuration change is |
| 164 | guaranteed atomic if multiple configuration changes are specified. |
| 165 | This function might sleep, depending on what the device driver has to |
| 166 | do to satisfy the request. All PWM device drivers must support this |
| 167 | entry point. |
| 168 | |
| 169 | |
| 170 | pwm_config_nosleep() -- Passes a pwm_channel_config structure to the |
| 171 | associated device driver. If the driver must sleep in order to |
| 172 | implement the requested configuration change, -EWOULDBLOCK is |
| 173 | returned. Users may call this function from interrupt handlers, for |
| 174 | example. This is the other main entry point into the PWM hardware |
| 175 | driver, but not all device drivers support this entry point. |
| 176 | |
| 177 | |
| 178 | pwm_synchronize(), pwm_unsynchronize() -- "Synchronizes" two or more |
| 179 | PWM channels, if the underlying hardware permits. (If it doesn't, the |
| 180 | framework facilitates emulating this capability but it is not yet |
| 181 | implemented). Synchronized channels will start and stop |
| 182 | simultaneously when any single channel in the group is started or |
| 183 | stopped. Use pwm_unsynchronize(..., NULL) to completely detach a |
| 184 | channel from any other synchronized channels. By default, all PWM |
| 185 | channels are unsynchronized. |
| 186 | |
| 187 | |
| 188 | pwm_set_handler() -- Defines an end-of-period callback. The indicated |
| 189 | function will be invoked in a worker thread at the end of each PWM |
| 190 | period, and can subsequently invoke pwm_config(), etc. Must be used |
| 191 | with extreme care for high-speed PWM outputs. Set the handler |
| 192 | function to NULL to un-set the handler. |
| 193 | |
| 194 | |
| 195 | |
| 196 | Implementing a PWM Device API Driver -- Functions for Driver Authors |
| 197 | |
| 198 | |
| 199 | Fill out the appropriate fields in a pwm_device structure, and submit |
| 200 | to pwm_register(): |
| 201 | |
| 202 | |
| 203 | bus_id -- the plain-text name of the device. Users will bind to a |
| 204 | channel on the device using this name plus the channel number. For |
| 205 | example, the Atmel PWMC's bus_id is "atmel_pwmc", the same as used by |
| 206 | the platform device driver (recommended). The first device registered |
| 207 | thereby receives bus_id "atmel_pwmc.0", which is what you put in |
| 208 | pwm_device.bus_id. Channels are then named "atmel_pwmc.0:[0-3]". |
| 209 | (Hint: just use pdev->dev.bus_id in your probe() method). |
| 210 | |
| 211 | |
| 212 | nchan -- the number of distinct output channels provided by the device. |
| 213 | |
| 214 | |
| 215 | request -- (optional) Invoked each time a user requests a channel. |
| 216 | Use to turn on clocks, clean up register states, etc. The framework |
| 217 | takes care of device locking/unlocking; you will see only successful |
| 218 | requests. |
| 219 | |
| 220 | |
| 221 | free -- (optional) Callback for each time a user relinquishes a |
| 222 | channel. The framework will have already stopped, unsynchronized and |
| 223 | un-handled the channel. Use to turn off clocks, etc. as necessary. |
| 224 | |
| 225 | |
| 226 | synchronize, unsynchronize -- (optional) Callbacks to |
| 227 | synchronize/unsynchronize channels. Some devices provide this |
| 228 | capability in hardware; for others, it can be emulated (see |
| 229 | atmel_pwmc.c's sync_mask for an example). |
| 230 | |
| 231 | |
| 232 | set_callback -- (optional) Invoked when a user requests a handler. If |
| 233 | the hardware supports an end-of-period interrupt, invoke the function |
| 234 | indicated during your interrupt handler. The callback function itself |
| 235 | is always internal to the API, and does not map directly to the user's |
| 236 | callback function. |
| 237 | |
| 238 | |
| 239 | config -- Invoked to change the device configuration, always from a |
| 240 | sleep-capable context. All the changes indicated must be performed |
| 241 | atomically, ideally synchronized to an end-of-period event (so that |
| 242 | you avoid short or long output pulses). You may sleep, etc. as |
| 243 | necessary within this function. |
| 244 | |
| 245 | |
| 246 | config_nosleep -- (optional) Invoked to change device configuration |
| 247 | from within a context that is not allowed to sleep. If you cannot |
| 248 | perform the requested configuration changes without sleeping, return |
| 249 | -EWOULDBLOCK. |
| 250 | |
| 251 | |
| 252 | |
| 253 | Acknowledgements |
| 254 | |
| 255 | |
| 256 | The author expresses his gratitude to the countless developers who |
| 257 | have reviewed and submitted feedback on the various versions of the |
| 258 | Generic PWM Device API code, and those who have submitted drivers and |
| 259 | applications that use the framework. You know who you are. ;) |
| 260 | |
| 261 | |
