README for omap3-pwm driver

Implements a driver to easily test the PWM outputs of an OMAP3 based Linux
system from userspace.

Should work with any OMAP3 board, but only tested with Gumstix Overo.

The default PWM used is PWM10. 

There is a ${MACHINE}-source-me.txt file that will set up your environment for
the cross-compilation. It assumes you are using an OE environment and it tries 
to be generic enough for both userland and kernel/module stuff. 

You should modify or create a similar script for pointing to the build system 
you are using.

If you modified your OE temp directory, then also update the OETMP variable in 
the appropriate ${MACHINE}-source-me.txt. I kind of tested overo and beagleboard, 
but I don't normally use the defaults.

Follow these steps to build. Using an overo for the example.

$ git clone git://github.com/scottellis/omap3-pwm.git
$ cd omap3-pwm
$ <edit> beagle-source-me.txt
$ source beagle-source-me.txt
$ make 

Next copy the pwm.ko file to your board.

Once on the system, use insmod to load using the optional frequency parameter.
The default frequency is 1024 Hz. Use multiples of two with a max of 16384.

pwm9_enable,pwm10_enable and pwm11_enable and frequency are load time parameters


root@beagleboard# ls
pwm.ko

root@beagleboard# insmod pwm.ko pwm9_enable=1

The driver implements a character device interface. When it loads, it will 
create a /dev/pwm9 entry.

To setup multiple pwm signals on the GPT9/10/11 you should use 

root@beagleboard# insmod pwm.ko pwm9_enable=1 pwm10_enable=1

This will work similarly for other combinations as well.


Then to issue commands you can use any program that can do file I/O. 
cat and echo will work. 

root@beagleboard# cat /dev/pwm9
PWM10 Frequency 1024 Hz Stopped

root@beagleboard# echo 50 > /dev/pwm9

root@beagleboard:~# cat /dev/pwm9
PWM10 Frequency 1024 Hz Duty Cycle 50%

root@beagleboard:~# echo 80 > /dev/pwm9

root@beagleboard:~# cat /dev/pwm9
PWM10 Frequency 1024 Hz Duty Cycle 80%

You can put an oscope on pin 28 of the expansion board to see the signal.
Use pin 15 for ground. Or you can measure the voltage on pin 28 and you'll
see the duty cycle percentage of 1.8v.

To change frequency/duty_cycle you can also use the ioctl() calls . 
To change the pulse direction i.e. a positive pulse pwm or a negative pulse pwm, make the SCPWM call to the ioctl interface.
Passing a value of 1 will cause a positive pulse while anyother value gives a negative pulse. 
By default the PWM signal has a positive pulse.


Currently you should follow this order to setup the frequency and duty cycle correctly
1) Set Frequency


2) Set Duty cycle


And after setting a new frequency it is important to reset the duty cycle you desire to use. The old duty cycle will not be automatically setup.

The driver takes care of muxing the output pin correctly and restores the original muxing when it unloads. 
The default muxing by Beagleboard for the PWM pins is to be GPIO. 



TODO:
1. Support switching PWM10 and 11 to use the 13MHz clock as FCLK
   instead of the default 32kHz clock if the user chooses. This gives
   more granularity for duty-cycle adjustments. It might be sufficient
   to support this only on driver load.

2. The outputs were for experimentation. I'd probably change them to
   be a little terser, more machine friendly.

3. Investigate one-shot mode

4. Investigate support for the prescaler in the TCLR config.



BEAGLEBOARD Note: The kernel config option CONFIG_OMAP_RESET_CLOCKS is enabled
in the default beagleboard defconfigs. You'll get an oops using pwm.ko with
this enabled. This is a kernel power saving feature. You'll need to disable this 
config option to use this driver. Below is a sample patch for linux-omap-2.6.32's
defconfig. Adjust for the kernel you are using. Gumstix users already have this
turned off in default kernels.

diff --git a/recipes/linux/linux-omap-2.6.32/beagleboard/defconfig b/recipes/linux/linux-omap-2.6.32/beagleboard/defconfig
index cebe1f5..2dad30c 100644
--- a/recipes/linux/linux-omap-2.6.32/beagleboard/defconfig
+++ b/recipes/linux/linux-omap-2.6.32/beagleboard/defconfig
@@ -241,7 +241,7 @@ CONFIG_ARCH_OMAP3=y
 #
 # CONFIG_OMAP_DEBUG_POWERDOMAIN is not set
 # CONFIG_OMAP_DEBUG_CLOCKDOMAIN is not set
-CONFIG_OMAP_RESET_CLOCKS=y
+# CONFIG_OMAP_RESET_CLOCKS is not set
 # CONFIG_OMAP_MUX is not set
 CONFIG_OMAP_MCBSP=y
 CONFIG_OMAP_MBOX_FWK=m