Changeset 774 for firmware/trunk/core/makingthings/pwm.c

Timestamp:

07/31/08 13:16:09 (5 months ago)

Author:

liamstask

Message:

- incorporating additions from #64
- can more easily configure PWM channels - timing, alignment, etc.
- more & better doc for PWM

Files:

• firmware/trunk/core/makingthings/pwm.c (modified) (4 diffs)

firmware/trunk/core/makingthings/pwm.c

@@ -19 +19 @@
   PWM - Pulse Width Modulation.
   Library of functions for the Make Application Board's PwmOut Subsystem.
-  //ToDo: DW choose which functions are public, and confirm/correct annotations
 */
 
@@ -59 +58 @@
 } Pwm;
 
-/** \defgroup Pwm PWM
-  The Pwm subsystem provides control of the 4 PWM outputs on the SAM7X.
-  The Pwm subsystem of the Controller Board can be used independently from the PWM_Out subsystem
-  of the Application Board, and in fact the AppBoard PwmOut relies on the Controller Board PWM.
+/** \defgroup Pwm PWM (Pulse Width Modulation)
+  The PWM subsystem provides control of the 4 PWM outputs on the SAM7X.
+
+  The Make Controller has 4 PWM lines.  These can each be configured separately and can control
+  up to 2 output lines directly, the 2 lines running either parallel or inverted.  For a very simple
+  start, just see Pwm_Set( ) and Pwm_Get( ) as these will start driving your PWMs immediately with
+  very little hassle.  
+
+  \section padjust Period adjustment of the PWM unit
+  Configuring and setting the clock for the PWM system can be quite a complicated matter.  Here are 
+  some of the relevant issues.
+  
+  Each of the 4 PWM channels is fed in a clock, as determined by its clock source:
+   - Clock source 0-10 represent the Master clock divided by 2 to the power of the Clock Source Value.  eg. a clock 
+   source value of 5 = a clock rate of MasterClock/(2^5)
+   - A value of 11 sets the Clock source to be generated by clock Divider A (Default)
+   - A value of 12 sets the Clock source to be generated by clock Divider B
+  
+  If either Clock Divider A or Clock Divider B is used, you can adjust their values individually to
+  allow the clock period to precisely match your needs.  Each clock divider has two values, a \b Mux value 
+  and a \b Divider value.  
+  
+  The mux works just like the clock source values, and chooses Master clock divided by 2 to 
+  the power of the Clock Source Value, eg. a DividerXMux value of 5 == a clock rate of MasterClock/(2^5).
+  The Divider value sets a linear divider, which is fed the clock value as selected by the Mux, and returns that 
+  clock value divided by the divider value.  This output value is what is fed out of the divider unit.  A output 
+  formula: 
+  \code output = MCLK / ( (2^DividerMux) * DividerValue ) \endcode
   
-  @see PWM_Out
+  The PWM subsystem of the Controller Board can be used independently from the \ref PwmOut 
+  library, since the \ref PwmOut library relies on the core PWM.
+
   \ingroup Core
   @{
@@ -99 +124 @@
   return Pwm.duty[ index ];
 }
-
-/** @}
-*/
 
 int Pwm_Start( int channel )
@@ -243 +265 @@
   return io;
 }
+
+/**
+  Adjust the clock period on Divider A.
+  See AT91SAM7X manual for more information p.421
+
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param val An int between 0 and 4096.
+  @return 0 on success.
+*/
+int Pwm_SetDividerA(int val)
+{ 
+  if( val < 0 || val > ( 1 << 12 ) )
+    return CONTROLLER_ERROR_ILLEGAL_PARAMETER_VALUE;
+
+  // First disable PWM controller for all 4 channels.
+  AT91C_BASE_PWMC->PWMC_DIS = 0x0000000f;
+
+  // Now Set the new Clock values
+  AT91C_BASE_PWMC->PWMC_MR = (AT91C_BASE_PWMC->PWMC_MR & 0xffff0000) | val;
+
+  // Re-enable the active channels
+  AT91C_BASE_PWMC->PWMC_ENA = Pwm.channels;
+  
+  return CONTROLLER_OK;
+}
+
+/**
+  Read the clock period on Divider A.
+
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @return The clock period on Divider A.
+*/
+int Pwm_GetDividerA()
+{
+  return (AT91C_BASE_PWMC->PWMC_MR & 0x0000ffff);
+}
+
+/**
+  Adjust the clock period on Divider B.
+  See AT91SAM7X manual for more information p.421
+
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param val An int between 0 and 4096.
+  @return 0 on success.
+*/
+int Pwm_SetDividerB(int val)
+{ 
+  if( val < 0 || val > ( 1 << 12 ) )
+    return CONTROLLER_ERROR_ILLEGAL_PARAMETER_VALUE;
+
+  //New function which adjusts the clock period on Divider A.
+  //See AT91SAM7X manual for more information p.421
+
+  // First disable PWM controller for all 4 channels.
+  AT91C_BASE_PWMC->PWMC_DIS = 0x0000000f;
+
+  // Now Set the new Clock values
+  AT91C_BASE_PWMC->PWMC_MR = (AT91C_BASE_PWMC->PWMC_MR & 0x0000ffff) | ( val << 16 );
+
+  // Re-enable the active channels
+  AT91C_BASE_PWMC->PWMC_ENA = Pwm.channels;
+  
+  return CONTROLLER_OK;
+}
+
+/**
+  Read the clock period on Divider B.
+
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @return The clock period on Divider B.
+*/
+int Pwm_GetDividerB()
+{
+  return (AT91C_BASE_PWMC->PWMC_MR >> 16);
+}
+
+/**
+  Set the clock divider for a particular channel.
+  For values 0-10, the Master_Clock is divided by (2^val).  For example,
+  for 4 the resulting period will be Master Clock / 16, as 2 ^ 4 == 16.
+
+  When val is 11, Clock Divider A is used.  When val is 12, Clock Divider B
+  is used.  Values other than 0 - 12 are not valid.
+
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param channel The PWM channel (0-3) you'd like to configure.
+  @param val The new clock divider.
+  @return 0 on success.
+*/
+int Pwm_SetClockSource(int channel, int val)
+{
+  if ( channel < 0 || channel > PWM_COUNT )
+    return CONTROLLER_ERROR_ILLEGAL_INDEX;
+
+  if ( val < 0 || val > 12 )
+    return CONTROLLER_ERROR_ILLEGAL_PARAMETER_VALUE;
+
+  AT91S_PWMC_CH *pwm = &AT91C_BASE_PWMC->PWMC_CH[ channel ];
+  int c = 1 << channel;
+
+  // Disable the Channel
+  AT91C_BASE_PWMC->PWMC_DIS = c;
+
+  // Set the Channel Divider Value
+  pwm->PWMC_CMR = (pwm->PWMC_CMR & 0x00000700) | val;
+  
+  // Re-enable the Channel
+  AT91C_BASE_PWMC->PWMC_ENA = c;
+
+  return CONTROLLER_OK;
+}
+
+/**
+  Read the clock source for a particular channel.
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param channel The PWM channel (0-3) whose channel you'd like to read.
+  @return The clock source.
+  @see Pwm_SetClockSource( )
+*/
+int Pwm_GetClockSource(int channel)
+{
+  if ( channel < 0 || channel > PWM_COUNT )
+    return CONTROLLER_ERROR_ILLEGAL_INDEX;
+
+  return (AT91C_BASE_PWMC->PWMC_CH[ channel ].PWMC_CMR & 0x0000000f);
+}
+
+/**
+  Set the wave form properties of the PWM contoller for a given channel.
+  The waveform properties are controlled by bits 0, 1, and 2.
+   - bit 0 sets whether the PWModule is Left aligned (0) or Center aligned (1)
+   - bit 1 sets whether the PWMoudle's polarity starts out low (0) or high (1)
+   - bit 2 is not supported at this time.
+
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param channel the PWM channel (0-3) that you want to configure
+  @param val The mask of values as described above.
+  @return 0 on success.
+*/
+int Pwm_SetWaveformProperties(int channel, int val)
+{
+  if ( channel < 0 || channel > PWM_COUNT )
+    return CONTROLLER_ERROR_ILLEGAL_INDEX;
+
+  if ( val < 0 || val > 3 )
+    return CONTROLLER_ERROR_ILLEGAL_PARAMETER_VALUE;
+
+  AT91S_PWMC_CH *pwm = &AT91C_BASE_PWMC->PWMC_CH[ channel ];
+  int c = 1 << channel;
+
+  // Disable the Channel
+  AT91C_BASE_PWMC->PWMC_DIS = c;
+
+  // Set the Channel Divider Value
+  pwm->PWMC_CMR = (pwm->PWMC_CMR & 0x0000040f) | ( val << 8 );
+  
+  // Re-enable the Channel
+  AT91C_BASE_PWMC->PWMC_ENA = c;
+
+  return CONTROLLER_OK;
+}
+
+/**
+  Read the waveform configuration of a specified PWM channel
+
+  Contributed by TheStigg - http://www.makingthings.com/author/thestigg
+  @param channel The PWM channel (0-3) to read from.
+  @return A bitmask describing the waveform configuration.
+  @see Pwm_SetWaveformProperties( )
+*/
+int Pwm_GetWaveformProperties(int channel)
+{
+  if ( channel < 0 || channel > PWM_COUNT )
+    return CONTROLLER_ERROR_ILLEGAL_INDEX;
+  
+  return ( (AT91C_BASE_PWMC->PWMC_CH[ channel ].PWMC_CMR >> 8) & 0x00000003 );
+}
+
+/** @}
+*/