From 2807d1bc327d052269af8b40240085b9f6d65563 Mon Sep 17 00:00:00 2001
From: Nathael Pajani <nathael.pajani@ed3l.fr>
Date: Sat, 18 Jun 2016 13:59:15 +0200
Subject: [PATCH] Adding comments to the pwm config structure and function
 Fixes to timer_on() function comments

---
 drivers/timers.c         |  5 +++--
 include/drivers/timers.h | 34 +++++++++++++++++++++++++++++++---
 2 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/drivers/timers.c b/drivers/timers.c
index 2c232fd..372090e 100644
--- a/drivers/timers.c
+++ b/drivers/timers.c
@@ -136,6 +136,7 @@ void timer_set_match(uint8_t timer_num, uint8_t channel, uint32_t val)
 	}
 }
 
+/* Configure the timer as PWM. Call to timer-specific function */
 void timer_pwm_config(uint8_t timer_num, const struct lpc_timer_pwm_config* conf)
 {
 	if (timer_num >= NUM_TIMERS)
@@ -149,8 +150,8 @@ void timer_pwm_config(uint8_t timer_num, const struct lpc_timer_pwm_config* conf
 
 
 /* Power up a timer.
- * clkrate is a divider of the main clock frequency chosen for your application
- *   as it will be used to divide the main clock to get the prescaler value.
+ * clkrate is the desired timer clock rate. It will be used to divide the main clock
+ *   to get the timer prescaler value.
  *   Set clkrate to 0 to disable the prescaler.
  * callback is the interrupt callback for this timer.
  */
diff --git a/include/drivers/timers.h b/include/drivers/timers.h
index 4a732a1..23b1c7c 100644
--- a/include/drivers/timers.h
+++ b/include/drivers/timers.h
@@ -59,17 +59,36 @@ enum lpc_timer_mode {
 };
 
 
+/*******************************************************************************/
 /* Configurations */
+
+/* PWM
+ * This structure is used for the timer_pwm_config() function.
+ * nb_channels is the number of PWM channels used
+ * outputs_initial_state defines whether the outputs start low or high at the beginning of
+ *   the PWM cycle. Support for this depends on the target. Some will allow a different
+ *   state for each output (then use one bit for each output, bit 0 for output 0, ...) while
+ *   some will require the same initial state for all output (then outputs_initial_state
+ *   can be either 0 for "low" or any positive value for "high")
+ * outputs[] is the list of outputs / channels corresponding to each 'match_values'
+ * period is the PWM cycle period, in timer clock cycles. It is the value to wich the timer
+ *   will count.
+ * match_values[] control the PWM channels duty-cycle. They are the timer values at wich
+ *   the corresponding outputs will toggle. They must be lower than or equal to the period
+ *   value.
+ */
 struct lpc_timer_pwm_config {
 	uint8_t nb_channels;
 	uint8_t outputs_initial_state;
+	uint8_t outputs[MAX_CHANNELS];
 	uint32_t period;
 	uint32_t match_values[MAX_CHANNELS];
-	uint8_t outputs[MAX_CHANNELS];
 };
 
 
 
+/*******************************************************************************/
+/* Operation structures, not for use by user programms */
 struct common_operations {
 	/* Running control */
 	void (*start)(uint8_t);
@@ -124,6 +143,15 @@ uint32_t timer_get_counter_val(uint8_t timer_num);
 /* Change the match value of a single timer channel */
 void timer_set_match(uint8_t timer_num, uint8_t channel, uint32_t val);
 
+/* PWM configuration in order to use the timer as a PWM controller.
+ * For the pwm_conf structure, refer to it's definition above..
+ * The Timer must be "on" (call timer_on() for this timer before the call to
+ *   timer_pwm_config(), with the disired clock rate, which will define the
+ *   length of a timer clock cycle, which is the base for the timer period
+ *   definition).
+ * The timer will not be started. User code must call timer_start() in order
+ *   to start the PWM.
+ */
 void timer_pwm_config(uint8_t timer_num, const struct lpc_timer_pwm_config* pwm_conf);
 
 
@@ -132,8 +160,8 @@ void timer_pwm_config(uint8_t timer_num, const struct lpc_timer_pwm_config* pwm_
 /* Init */
 
 /* Power up a timer.
- * clkrate is a divider of the main clock frequency chosen for your application
- *   as it will be used to divide the main clock to get the prescaler value.
+ * clkrate is the desired timer clock rate. It will be used to divide the main clock
+ *   to get the timer prescaler value.
  *   Set clkrate to 0 to disable the prescaler.
  * callback is used for all the possible timer interrupts (activated using the
  *   config field in timer_config struct upon timer setup)
-- 
2.43.0