diff options
Diffstat (limited to 'target/linux/generic-2.6/files/Documentation/pwm.txt')
| -rw-r--r-- | target/linux/generic-2.6/files/Documentation/pwm.txt | 260 |
1 files changed, 0 insertions, 260 deletions
diff --git a/target/linux/generic-2.6/files/Documentation/pwm.txt b/target/linux/generic-2.6/files/Documentation/pwm.txt deleted file mode 100644 index 2c41ca5867..0000000000 --- a/target/linux/generic-2.6/files/Documentation/pwm.txt +++ /dev/null @@ -1,260 +0,0 @@ - Generic PWM Device API - - February 1, 2010 - Bill Gatliff - <bgat@billgatliff.com> - - - -The code in drivers/pwm and include/linux/pwm/ implements an API for -applications involving pulse-width-modulation signals. This document -describes how the API implementation facilitates both PWM-generating -devices, and users of those devices. - - - -Motivation - -The primary goals for implementing the "generic PWM API" are to -consolidate the various PWM implementations within a consistent and -redundancy-reducing framework, and to facilitate the use of -hotpluggable PWM devices. - -Previous PWM-related implementations within the Linux kernel achieved -their consistency via cut-and-paste, but did not need to (and didn't) -facilitate more than one PWM-generating device within the system--- -hotplug or otherwise. The Generic PWM Device API might be most -appropriately viewed as an update to those implementations, rather -than a complete rewrite. - - - -Challenges - -One of the difficulties in implementing a generic PWM framework is the -fact that pulse-width-modulation applications involve real-world -signals, which often must be carefully managed to prevent destruction -of hardware that is linked to those signals. A DC motor that -experiences a brief interruption in the PWM signal controlling it -might destructively overheat; it could suddenly change speed, losing -synchronization with a sensor; it could even suddenly change direction -or torque, breaking the mechanical device connected to it. - -(A generic PWM device framework is not directly responsible for -preventing the above scenarios: that responsibility lies with the -hardware designer, and the application and driver authors. But it -must to the greatest extent possible make it easy to avoid such -problems). - -A generic PWM device framework must accommodate the substantial -differences between available PWM-generating hardware devices, without -becoming sub-optimal for any of them. - -Finally, a generic PWM device framework must be relatively -lightweight, computationally speaking. Some PWM users demand -high-speed outputs, plus the ability to regulate those outputs -quickly. A device framework must be able to "keep up" with such -hardware, while still leaving time to do real work. - -The Generic PWM Device API is an attempt to meet all of the above -requirements. At its initial publication, the API was already in use -managing small DC motors, sensors and solenoids through a -custom-designed, optically-isolated H-bridge driver. - - - -Functional Overview - -The Generic PWM Device API framework is implemented in -include/linux/pwm/pwm.h and drivers/pwm/pwm.c. The functions therein -use information from pwm_device, pwm_channel and pwm_channel_config -structures to invoke services in PWM peripheral device drivers. -Consult drivers/pwm/atmel-pwm.c for an example driver. - -There are two classes of adopters of the PWM framework: - - "Users" -- those wishing to employ the API merely to produce PWM - signals; once they have identified the appropriate physical output - on the platform in question, they don't care about the details of - the underlying hardware - - "Driver authors" -- those wishing to bind devices that can generate - PWM signals to the Generic PWM Device API, so that the services of - those devices become available to users. Assuming the hardware can - support the needs of a user, driver authors don't care about the - details of the user's application - -Generally speaking, users will first invoke pwm_request() to obtain a -handle to a PWM device. They will then pass that handle to functions -like pwm_duty_ns() and pwm_period_ns() to set the duty cycle and -period of the PWM signal, respectively. They will also invoke -pwm_start() and pwm_stop() to turn the signal on and off. - -The Generic PWM API framework also provides a sysfs interface to PWM -devices, which is adequate for basic application needs and testing. - -Driver authors fill out a pwm_device structure, which describes the -capabilities of the PWM hardware being constructed--- including the -number of distinct output "channels" the peripheral offers. They then -invoke pwm_register() (usually from within their device's probe() -handler) to make the PWM API aware of their device. The framework -will call back to the methods described in the pwm_device structure as -users begin to configure and utilize the hardware. - -Note that PWM signals can be produced by a variety of peripherals, -beyond the true "PWM hardware" offered by many system-on-chip devices. -Other possibilities include timer/counters with compare-match -capabilities, carefully-programmed synchronous serial ports -(e.g. SPI), and GPIO pins driven by kernel interval timers. With a -proper pwm_device structure, these devices and pseudo-devices can all -be accommodated by the Generic PWM Device API framework. - - - -Using the API to Generate PWM Signals -- Basic Functions for Users - - -pwm_request() -- Returns a pwm_channel pointer, which is subsequently -passed to the other user-related PWM functions. Once requested, a PWM -channel is marked as in-use and subsequent requests prior to -pwm_free() will fail. - -The names used to refer to PWM devices are defined by driver authors. -Typically they are platform device bus identifiers, and this -convention is encouraged for consistency. - - -pwm_free() -- Marks a PWM channel as no longer in use. The PWM device -is stopped before it is released by the API. - - -pwm_period_ns() -- Specifies the PWM signal's period, in nanoseconds. - - -pwm_duty_ns() -- Specifies the PWM signal's active duration, in nanoseconds. - - -pwm_duty_percent() -- Specifies the PWM signal's active duration, as a -percentage of the current period of the signal. NOTE: this value is -not recalculated if the period of the signal is subsequently changed. - - -pwm_start(), pwm_stop() -- Turns the PWM signal on and off. Except -where stated otherwise by a driver author, signals are stopped at the -end of the current period, at which time the output is set to its -inactive state. - - -pwm_polarity() -- Defines whether the PWM signal output's active -region is "1" or "0". A 10% duty-cycle, polarity=1 signal will -conventionally be at 5V (or 3.3V, or 1000V, or whatever the platform -hardware does) for 10% of the period. The same configuration of a -polarity=0 signal will be at 5V (or 3.3V, or ...) for 90% of the -period. - - - -Using the API to Generate PWM Signals -- Advanced Functions - - -pwm_config() -- Passes a pwm_channel_config structure to the -associated device driver. This function is invoked by pwm_start(), -pwm_duty_ns(), etc. and is one of two main entry points to the PWM -driver for the hardware being used. The configuration change is -guaranteed atomic if multiple configuration changes are specified. -This function might sleep, depending on what the device driver has to -do to satisfy the request. All PWM device drivers must support this -entry point. - - -pwm_config_nosleep() -- Passes a pwm_channel_config structure to the -associated device driver. If the driver must sleep in order to -implement the requested configuration change, -EWOULDBLOCK is -returned. Users may call this function from interrupt handlers, for -example. This is the other main entry point into the PWM hardware -driver, but not all device drivers support this entry point. - - -pwm_synchronize(), pwm_unsynchronize() -- "Synchronizes" two or more -PWM channels, if the underlying hardware permits. (If it doesn't, the -framework facilitates emulating this capability but it is not yet -implemented). Synchronized channels will start and stop -simultaneously when any single channel in the group is started or -stopped. Use pwm_unsynchronize(..., NULL) to completely detach a -channel from any other synchronized channels. By default, all PWM -channels are unsynchronized. - - -pwm_set_handler() -- Defines an end-of-period callback. The indicated -function will be invoked in a worker thread at the end of each PWM -period, and can subsequently invoke pwm_config(), etc. Must be used -with extreme care for high-speed PWM outputs. Set the handler -function to NULL to un-set the handler. - - - -Implementing a PWM Device API Driver -- Functions for Driver Authors - - -Fill out the appropriate fields in a pwm_device structure, and submit -to pwm_register(): - - -bus_id -- the plain-text name of the device. Users will bind to a -channel on the device using this name plus the channel number. For -example, the Atmel PWMC's bus_id is "atmel_pwmc", the same as used by -the platform device driver (recommended). The first device registered -thereby receives bus_id "atmel_pwmc.0", which is what you put in -pwm_device.bus_id. Channels are then named "atmel_pwmc.0:[0-3]". -(Hint: just use pdev->dev.bus_id in your probe() method). - - -nchan -- the number of distinct output channels provided by the device. - - -request -- (optional) Invoked each time a user requests a channel. -Use to turn on clocks, clean up register states, etc. The framework -takes care of device locking/unlocking; you will see only successful -requests. - - -free -- (optional) Callback for each time a user relinquishes a -channel. The framework will have already stopped, unsynchronized and -un-handled the channel. Use to turn off clocks, etc. as necessary. - - -synchronize, unsynchronize -- (optional) Callbacks to -synchronize/unsynchronize channels. Some devices provide this -capability in hardware; for others, it can be emulated (see -atmel_pwmc.c's sync_mask for an example). - - -set_callback -- (optional) Invoked when a user requests a handler. If -the hardware supports an end-of-period interrupt, invoke the function -indicated during your interrupt handler. The callback function itself -is always internal to the API, and does not map directly to the user's -callback function. - - -config -- Invoked to change the device configuration, always from a -sleep-capable context. All the changes indicated must be performed -atomically, ideally synchronized to an end-of-period event (so that -you avoid short or long output pulses). You may sleep, etc. as -necessary within this function. - - -config_nosleep -- (optional) Invoked to change device configuration -from within a context that is not allowed to sleep. If you cannot -perform the requested configuration changes without sleeping, return --EWOULDBLOCK. - - - -Acknowledgements - - -The author expresses his gratitude to the countless developers who -have reviewed and submitted feedback on the various versions of the -Generic PWM Device API code, and those who have submitted drivers and -applications that use the framework. You know who you are. ;) - |