[kernel] Add the generic PWM api from Bill Gatliff (experimental). Ignore the leds...
[openwrt/svn-archive/archive.git] / target / linux / generic-2.6 / files / Documentation / pwm.txt
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