beagle: pwm polishing

	. added a README to pwm
	. added select_pwmss() to select pwmss-generic registers, as opposed
	  to PWM-specific registers
	. added pwmss_clock_en_status(), beagle_pwmss_is_running() and pwmss_tb_clock_check()
	. other API improvements
	. style improvements

1 files changed, 68 insertions, 45 deletions

diff --git a/c/src/lib/libbsp/arm/beagle/include/bbb-pwm.h b/c/src/lib/libbsp/arm/beagle/include/bbb-pwm.h
index ef016f036b..cf5d6fe552 100644
--- a/c/src/lib/libbsp/arm/beagle/include/bbb-pwm.h
+++ b/c/src/lib/libbsp/arm/beagle/include/bbb-pwm.h
@@ -3,11 +3,11 @@
  *
  * @ingroup arm_beagle
  *
- * @brief BeagleBone Black BSP definitions.
+ * @brief BeagleBone Black PWM support definitions.
  */
 
 /**
- * Copyright (c) 2016 Punit Vara <punitvara at gmail.com>
+ * Copyright (c) 2016 Punit Vara <punitvara@gmail.com>
  *
  * The license and distribution terms for this file may be
  * found in the file LICENSE in this distribution or at
@@ -31,43 +31,53 @@ extern "C" {
 #define BBB_CONTROL_CONF_GPMC_AD(n)   (0x800 + (n * 4))
 #define BBB_CONTROL_CONF_LCD_DATA(n)   (0x8a0 + (n * 4))
 
-#define BBB_PWMSS_COUNT       3
-#define BBB_PWMSS0  0
-#define BBB_PWMSS1  1  
-#define BBB_PWMSS2  2
-
-#define BBB_P8_13_2B  3
-#define BBB_P8_19_2A  4
-#define BBB_P8_45_2A  5
-#define BBB_P8_46_2B  6
-#define BBB_P8_34_1B  7
-#define BBB_P8_36_1A  8
-#define BBB_P9_14_1A  9
-#define BBB_P9_16_1B  10
-#define BBB_P9_21_0B  11
-#define BBB_P9_22_0A  12
-#define BBB_P9_29_0B  13
-#define BBB_P9_31_0A  14
-
-#define BBB_MUX0      0
-#define BBB_MUX1      1
-#define BBB_MUX2      2
-#define BBB_MUX3      3
-#define BBB_MUX4      4
-#define BBB_MUX5      5
-#define BBB_MUX6      6
-#define BBB_MUX7      7
-
-#define BBB_EPWM1     1
-#define BBB_EPWM2     2
-#define BBB_EPWM0     0
+/**
+ * @brief The set of possible PWM subsystem module
+ *
+ * Enumerated type to define various instance of pwm module.
+ */
+typedef enum{
+  BBB_PWMSS0 = 0,
+  BBB_PWMSS1,
+  BBB_PWMSS2,
+  BBB_PWMSS_COUNT
+}BBB_PWMSS;
+
+typedef enum{
+  BBB_P8_13_2B = 3,
+  BBB_P8_19_2A,
+  BBB_P8_45_2A,
+  BBB_P8_46_2B,
+  BBB_P8_34_1B,
+  BBB_P8_36_1A,
+  BBB_P9_14_1A,
+  BBB_P9_16_1B,
+  BBB_P9_21_0B,
+  BBB_P9_22_0A,
+  BBB_P9_29_0B,
+  BBB_P9_31_0A
+}bbb_pwm_pin_t;
+
+#define BBB_P8_13_MUX_PWM 4 
+#define BBB_P8_19_MUX_PWM 4
+#define BBB_P8_45_MUX_PWM 3
+#define BBB_P8_46_MUX_PWM 3
+#define BBB_P8_34_MUX_PWM 2
+#define BBB_P8_36_MUX_PWM 2
+#define BBB_P9_14_MUX_PWM 6
+#define BBB_P9_16_MUX_PWM 6
+#define BBB_P9_21_MUX_PWM 3
+#define BBB_P9_22_MUX_PWM 3
+#define BBB_P9_29_MUX_PWM 1
+#define BBB_P9_31_MUX_PWM 1
+#define BBB_PWM_FREQ_THRESHOLD 0.5f
 
 /**
  * @brief  BeagleBone Black PWM API.
  */
 
 /**
- * @brief This function intilize clock and pinmuxing for pwm sub system.
+ * @brief This function intilizes clock for pwm sub system.
  *
  * @param PWMSS_ID It is the instance number of EPWM of pwm sub system.
  * 
@@ -75,20 +85,20 @@ extern "C" {
  * @return false if not successful
  *
  **/
-bool beagle_pwm_init(uint32_t pwmss_id);
+bool beagle_pwm_init(BBB_PWMSS pwmss_id);
 
 /* PWMSS setting
  *      set pulse argument of epwm module
  *
  *      @param pwm_id    : EPWMSS number , 0~2
  *      @param pwm_freq : frequency to be generated
- *      @param dutyA    : Duty Cycle in ePWM A
- *      @param dutyB    : Duty Cycle in ePWM B
+ *      @param dutyA    : Duty Cycle(in percentage) in PWM channel A
+ *      @param dutyB    : Duty Cycle(in percentage) in PWM channel B
  *
  *      @return         : 1 for success
  *      @return         : 0 for failed
  *
- *      @example        :  PWMSS_Setting(0 , 50.0f , 50.0f , 25.0f);      // Generate 50HZ pwm in PWM0 ,
+ *      @example        :  beagle_pwm_configure(0 , 50.0f , 50.0f , 25.0f);      // Generate 50HZ pwm in PWM0 ,
  *                                                                              // duty cycle is 50% for ePWM0A , 25% for ePWM0B
  *
  *      @Note :
@@ -105,12 +115,12 @@ bool beagle_pwm_init(uint32_t pwmss_id);
  *              Divisor = CLKDIV * HSPCLKDIV
  *                      1 TBPRD : 10 ns (default)
  *                      65535 TBPRD : 655350 ns
- *                      65535 TBPRD : 655350 * Divisor ns  = X TBPRD : Cyclens
+ *                      65535 TBPRD : 655350 * Divisor ns  = X TBPRD : Cycle
  *
  *              accrooding to that , we must find a Divisor value , let X nearest 65535 .
- *              so , Divisor must  Nearest Cyclens/655350
+ *              so , Divisor must  Nearest Cycle/655350
  */
-int beagle_pwmss_setting(uint32_t pwm_id, float pwm_freq, float dutyA, float dutyB);
+int beagle_pwm_configure(BBB_PWMSS pwm_id, float pwm_freq, float duty_a, float duty_b);
 
 /**
  * @brief   This API enables the particular PWM module.
@@ -121,10 +131,10 @@ int beagle_pwmss_setting(uint32_t pwm_id, float pwm_freq, float dutyA, float dut
  * @return  false if fail
  *
  **/
-bool beagle_ehrpwm_enable(uint32_t pwmid);
+bool beagle_pwm_enable(BBB_PWMSS pwmid);
 
 /**
- * @brief   This API disables the HR sub-module.
+ * @brief   This API disables the particular PWM module.
  *
  * @param   pwmid  It is the instance number of EPWM of pwm sub system.
  *
@@ -132,10 +142,10 @@ bool beagle_ehrpwm_enable(uint32_t pwmid);
  * @return  false if fail
  *
  **/
-bool beagle_ehrpwm_disable(uint32_t pwmid);
+bool beagle_pwm_disable(BBB_PWMSS pwmid);
 
 /**
- * @brief   This function Enables pinmuxing for PWM module.
+ * @brief   This function enables pinmuxing for PWM module.
  *
  * @param   pin_no  It is individual pin at which freuqency need to be generated.
  *                  It should be according to pwm sub system.
@@ -146,7 +156,20 @@ bool beagle_ehrpwm_disable(uint32_t pwmid);
  * @return  false if fail
  *
  **/
-bool beagle_epwm_pinmux_setup(uint32_t pin_no, uint32_t pwm_id);
+bool beagle_pwm_pinmux_setup(bbb_pwm_pin_t pin_no, BBB_PWMSS pwm_id);
+
+/**
+ * @brief   This function determines whether PWMSS-wide clocks enabled or not.
+ *
+ * @param   pwmss_id  It is the instance number of PWMSS which clocks need to be
+ *                    checked.
+ * 
+ * @return  true if successful
+ * @return  false if fail
+ *
+ **/
+bool beagle_pwmss_is_running(unsigned int pwmss_id);
+
 
 #ifdef __cplusplus
 }