cleanup: comments in adc modules

No code changes, other than renaming a couple of static functions.

BUG=none
BRANCH=none
TEST=build falco

Change-Id: I29b835d273aa1aba66d9d40536eae2eb12207f66
Signed-off-by: Randall Spangler <rspangler@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/174530

5 files changed, 31 insertions, 15 deletions

diff --git a/chip/lm4/adc.c b/chip/lm4/adc.c
index b3e24809a8..e41386c25f 100644
--- a/chip/lm4/adc.c
+++ b/chip/lm4/adc.c
@@ -40,11 +40,12 @@ static void configure_gpio(void)
  * @param seq		Sequencer to read
  * @return Raw ADC value.
  */
-static int lm4_adc_flush_and_read(enum lm4_adc_sequencer seq)
+static int flush_and_read(enum lm4_adc_sequencer seq)
 {
 	/*
-	 * TODO: right now we have only a single channel so this is simple.
-	 * When we have multiple channels, should we...
+	 * This is currently simple because we can dedicate a sequencer to each
+	 * ADC channel.  If we have enough channels that's no longer possible,
+	 * this code will need to become more complex.  For example, we could:
 	 *
 	 * 1) Read them all using a timer interrupt, and then return the most
 	 * recent value?  This is lowest-latency for the caller, but won't
@@ -93,7 +94,7 @@ static int lm4_adc_flush_and_read(enum lm4_adc_sequencer seq)
  * @param ssctl		Value for sampler sequencer control register
  *
  */
-static void lm4_adc_configure(const struct adc_t *adc)
+static void adc_configure(const struct adc_t *adc)
 {
 	const enum lm4_adc_sequencer seq = adc->sequencer;
 
@@ -126,7 +127,7 @@ int adc_read_channel(enum adc_channel ch)
 	clock_enable_peripheral(CGC_OFFSET_ADC, 0x1,
 			CGC_MODE_RUN | CGC_MODE_SLEEP);
 
-	rv = lm4_adc_flush_and_read(adc->sequencer);
+	rv = flush_and_read(adc->sequencer);
 
 	/* Disable ADC0 module to conserve power. */
 	clock_disable_peripheral(CGC_OFFSET_ADC, 0x1,
@@ -245,7 +246,7 @@ static void adc_init(void)
 
 	/* Initialize ADC sequencer */
 	for (i = 0; i < ADC_CH_COUNT; ++i)
-		lm4_adc_configure(adc_channels + i);
+		adc_configure(adc_channels + i);
 
 	/* Disable ADC0 module until it is needed to conserve power. */
 	clock_disable_peripheral(CGC_OFFSET_ADC, 0x1,
diff --git a/chip/lm4/adc_chip.h b/chip/lm4/adc_chip.h
index 45c9ef13a4..736e6f113e 100644
--- a/chip/lm4/adc_chip.h
+++ b/chip/lm4/adc_chip.h
@@ -5,8 +5,8 @@
 
 /* LM4-specific ADC module for Chrome EC */
 
-#ifndef __CROS_EC_LM4_ADC_H
-#define __CROS_EC_LM4_ADC_H
+#ifndef __CROS_EC_ADC_CHIP_H
+#define __CROS_EC_ADC_CHIP_H
 
 enum lm4_adc_sequencer
 {
@@ -30,6 +30,10 @@ struct adc_t {
 	uint8_t gpio_mask;
 };
 
+/*
+ * Boards must provide this list of ADC channel definitions.  This must match
+ * the enum adc_channel list provided by the board.
+ */
 extern const struct adc_t adc_channels[];
 
 /* Minimum and maximum values returned by raw ADC read. */
@@ -42,4 +46,4 @@ extern const struct adc_t adc_channels[];
 /* Dummy value for "channel" in adc_t if we don't have an external channel. */
 #define LM4_AIN_NONE (-1)
 
-#endif /* __CROS_EC_LM4_ADC_H */
+#endif /* __CROS_EC_ADC_CHIP_H */
diff --git a/chip/stm32/adc-stm32l.c b/chip/stm32/adc-stm32l.c
index 0dc1d76743..75b640fde1 100644
--- a/chip/stm32/adc-stm32l.c
+++ b/chip/stm32/adc-stm32l.c
@@ -126,9 +126,10 @@ static void adc_release(void)
 		clock_enable_module(MODULE_ADC, 0);
 		restore_clock = 0;
 	}
+
 	/*
-	 * Always power down ADC.
-	 * TODO(victoryang): Can we leave ADC powered?
+	 * Power down the ADC.  The ADC consumes a non-trivial amount of power,
+	 * so it's wasteful to leave it on.
 	 */
 	if (adc_powered())
 		STM32_ADC_CR2 = 0;
diff --git a/chip/stm32/adc_chip.h b/chip/stm32/adc_chip.h
index 98141ea2d2..bc493ea75b 100644
--- a/chip/stm32/adc_chip.h
+++ b/chip/stm32/adc_chip.h
@@ -5,8 +5,8 @@
 
 /* STM32-specific ADC module for Chrome EC */
 
-#ifndef __CROS_EC_STM32_ADC_H
-#define __CROS_EC_STM32_ADC_H
+#ifndef __CROS_EC_ADC_CHIP_H
+#define __CROS_EC_ADC_CHIP_H
 
 /* Data structure to define ADC channels. */
 struct adc_t {
@@ -17,6 +17,10 @@ struct adc_t {
 	int channel;
 };
 
+/*
+ * Boards must provide this list of ADC channel definitions.  This must match
+ * the enum adc_channel list provided by the board.
+ */
 extern const struct adc_t adc_channels[];
 
 /* Minimum and maximum values returned by adc_read_channel(). */
@@ -26,4 +30,4 @@ extern const struct adc_t adc_channels[];
 /* Just plain id mapping for code readability */
 #define STM32_AIN(x) (x)
 
-#endif /* __CROS_EC_STM32_ADC_H */
+#endif /* __CROS_EC_ADC_CHIP_H */
diff --git a/include/adc.h b/include/adc.h
index 8c5dda02d5..3ff88b77f9 100644
--- a/include/adc.h
+++ b/include/adc.h
@@ -10,7 +10,13 @@
 
 #include "common.h"
 
-#define ADC_READ_ERROR -1
+#define ADC_READ_ERROR -1  /* Value returned by adc_read_channel() on error */
+
+/*
+ * Boards which use the ADC interface must provide enum adc_channel in the
+ * board.h file.  See chip/$CHIP/adc_chip.h for additional chip-specific
+ * requirements.
+ */
 
 /**
  * Read an ADC channel.