Clean up LED and onewire modules

No functional changes.

BUG=chrome-os-partner:15579
BRANCH=none
TEST=powerled red, then powerled green

Change-Id: I595b725c14d94133f7f151d0b92cabe0e0bcf4ca
Signed-off-by: Randall Spangler <rspangler@chromium.org>
Reviewed-on: https://gerrit.chromium.org/gerrit/36577
Reviewed-by: Bill Richardson <wfrichar@chromium.org>

5 files changed, 111 insertions, 61 deletions

diff --git a/chip/lm4/onewire.c b/chip/lm4/onewire.c
index 08fa66a372..082ce1238a 100644
--- a/chip/lm4/onewire.c
+++ b/chip/lm4/onewire.c
@@ -13,10 +13,12 @@
 
 #define ONEWIRE_PIN (1<<2)  /* One-wire pin mask (on GPIO H) */
 
-/* Standard speed; all timings padded by 2 usec for safety.
+/*
+ * Standard speed; all timings padded by 2 usec for safety.
  *
  * Note that these timing are actually _longer_ than legacy 1-wire standard
- * speed because we're running the 1-wire bus at 3.3V instead of 5V. */
+ * speed because we're running the 1-wire bus at 3.3V instead of 5V.
+ */
 #define T_RSTL 602  /* Reset low pulse; 600-960 us */
 #define T_MSP   72  /* Presence detect sample time; 70-75 us */
 #define T_RSTH (68 + 260 + 5 + 2) /* Reset high; tPDHmax + tPDLmax + tRECmin */
@@ -28,8 +30,9 @@
 		     * T_RL since that's how long the signal takes to be pulled
 		     * up on our board.  */
 
-
-/* Output low on the bus for <usec> us, then switch back to open-drain input */
+/**
+ * Output low on the bus for <usec> us, then switch back to open-drain input.
+ */
 static void output0(int usec)
 {
 	LM4_GPIO_DIR(LM4_GPIO_H) |= ONEWIRE_PIN;
@@ -38,15 +41,17 @@ static void output0(int usec)
 	LM4_GPIO_DIR(LM4_GPIO_H) &= ~ONEWIRE_PIN;
 }
 
-
-/* Read the signal line */
+/**
+ *  Read the signal line.
+ */
 static int readline(void)
 {
 	return LM4_GPIO_DATA(LM4_GPIO_H, ONEWIRE_PIN) ? 1 : 0;
 }
 
-
-/* Read a bit */
+/**
+ * Read a bit.
+ */
 static int readbit(void)
 {
 	int bit;
@@ -65,8 +70,9 @@ static int readbit(void)
 	return bit;
 }
 
-
-/* Write a bit */
+/**
+ * Write a bit.
+ */
 static void writebit(int bit)
 {
 	if (bit) {
@@ -78,28 +84,32 @@ static void writebit(int bit)
 	}
 }
 
-
 int onewire_reset(void)
 {
 	/* Start transaction with master reset pulse */
 	output0(T_RSTL);
 
-	/* Wait for presence detect sample time */
-	udelay(T_MSP);
-	/* Alternately, we could poll waiting for a 1-bit indicating our pulse
+	/* Wait for presence detect sample time.
+	 *
+	 * (Alternately, we could poll waiting for a 1-bit indicating our pulse
 	 * has let go, then poll up to max time waiting for a 0-bit indicating
-	 * the slave has responded. */
+	 * the slave has responded.)
+	 */
+	udelay(T_MSP);
+
 	if (readline() != 0)
 		return EC_ERROR_UNKNOWN;
 
-	/* Wait for end of presence pulse */
-	/* Alternately, we could poll waiting for a 1-bit */
+	/*
+	 * Wait for end of presence pulse.
+	 *
+	 * (Alternately, we could poll waiting for a 1-bit.)
+	 */
 	udelay(T_RSTH - T_MSP);
 
 	return EC_SUCCESS;
 }
 
-
 int onewire_read(void)
 {
 	int data = 0;
@@ -111,7 +121,6 @@ int onewire_read(void)
 	return data;
 }
 
-
 void onewire_write(int data)
 {
 	int i;
@@ -120,20 +129,10 @@ void onewire_write(int data)
 		writebit((data >> i) & 0x01);  /* LSB first */
 }
 
-/*****************************************************************************/
-/* Initialization */
-
-/* Configures GPIOs for the module. */
-static void configure_gpio(void)
+static void onewire_init(void)
 {
 	/* Configure 1-wire pin as open-drain GPIO */
 	gpio_set_alternate_function(LM4_GPIO_H, ONEWIRE_PIN, 0);
 	LM4_GPIO_ODR(LM4_GPIO_H) |= ONEWIRE_PIN;
 }
-
-static void onewire_init(void)
-{
-	/* Configure GPIOs */
-	configure_gpio();
-}
 DECLARE_HOOK(HOOK_INIT, onewire_init, HOOK_PRIO_DEFAULT);
diff --git a/chip/stm32/power_led.c b/chip/stm32/power_led.c
index bc354ee492..09d9d426cd 100644
--- a/chip/stm32/power_led.c
+++ b/chip/stm32/power_led.c
@@ -37,11 +37,15 @@ void powerled_set_state(enum powerled_state new_state)
 	task_wake(TASK_ID_POWERLED);
 }
 
-/* set board-level power LED config options (e.g. manual off/on, PWM) */
+/**
+ * Set board-level power LED config options (e.g. manual off/on, PWM).
+ */
 void board_power_led_config(enum powerled_state config)
 		__attribute__((weak, alias("__board_power_led_config")));
 
-/* Provide a default function in case the board doesn't have one */
+/**
+ * Default config function in case the board doesn't have one.
+ */
 void __board_power_led_config(enum powerled_config config)
 {
 }
@@ -50,10 +54,10 @@ static void power_led_use_pwm(void)
 {
 	board_power_led_config(POWERLED_CONFIG_PWM);
 
-	/* enable TIM2 clock */
+	/* Enable TIM2 clock */
 	STM32_RCC_APB1ENR |= 0x1;
 
-	/* disable counter during setup */
+	/* Disable counter during setup */
 	STM32_TIM_CR1(2) = 0x0000;
 
 	/*
@@ -74,10 +78,10 @@ static void power_led_use_pwm(void)
 	/* CC2 output enable, active low */
 	STM32_TIM_CCER(2) = (1 << 4) | (1 << 5);
 
-	/* generate update event to force loading of shadow registers */
+	/* Generate update event to force loading of shadow registers */
 	STM32_TIM_EGR(2) |= 1;
 
-	/* enable auto-reload preload, start counting */
+	/* Enable auto-reload preload, start counting */
 	STM32_TIM_CR1(2) |= (1 << 7) | (1 << 0);
 
 	led_config = POWERLED_CONFIG_PWM;
@@ -102,7 +106,9 @@ static void power_led_set_duty(int percent)
 	STM32_TIM_CCR2(2) = (STM32_TIM_ARR(2) / 100) * percent;
 }
 
-/* returns the timeout period (in us) for current step */
+/**
+ * Return the timeout period (in us) for the current step.
+ */
 static int power_led_step(void)
 {
 	int state_timeout = 0;
@@ -152,13 +158,13 @@ void power_led_task(void)
 			state_timeout = -1;
 			break;
 		case POWERLED_STATE_OFF:
-			/* reconfigure GPIO to disable the LED */
+			/* Reconfigure GPIO to disable the LED */
 			if (led_config != POWERLED_CONFIG_MANUAL_OFF)
 				power_led_manual_off();
 			state_timeout = -1;
 			break;
 		case POWERLED_STATE_SUSPEND:
-			/* drive using PWM with variable duty cycle */
+			/* Drive using PWM with variable duty cycle */
 			if (led_config != POWERLED_CONFIG_PWM)
 				power_led_use_pwm();
 			state_timeout = power_led_step();
diff --git a/common/power_led.c b/common/power_led.c
index 8647619f39..1e4b89505b 100644
--- a/common/power_led.c
+++ b/common/power_led.c
@@ -17,8 +17,13 @@ static const uint8_t led_masks[POWERLED_COLOR_COUNT] = {0xff, 0xfe, 0xfc, 0xfd};
 static const char * const color_names[POWERLED_COLOR_COUNT] = {
 	"off", "red", "yellow", "green"};
 
-
-/* Set the power LED GPIO controller outputs to the specified mask. */
+/**
+ * Set the power LED GPIO controller outputs
+ *
+ * @param mask		Mask of outputs to enable
+ *
+ * @return EC_SUCCESS, or non-zero if error.
+ */
 static int powerled_set_mask(int mask)
 {
 	int rv;
@@ -45,32 +50,34 @@ static int powerled_set_mask(int mask)
 	return EC_SUCCESS;
 }
 
-
 int powerled_set(enum powerled_color color)
 {
 	int rv = EC_SUCCESS;
 	int i;
 
-	/* 1-wire communication can fail for timing reasons in the current
+	/*
+	 * 1-wire communication can fail for timing reasons in the current
 	 * system.  We have a limited timing window to send/receive bits, but
 	 * we can't disable interrupts for the rest of the system to guarantee
 	 * we hit that window.  Instead, simply retry the low-level command a
-	 * few times. */
+	 * few times.
+	 */
 	for (i = 0; i < POWERLED_RETRIES; i++) {
 		rv = powerled_set_mask(led_masks[color]);
 		if (rv == EC_SUCCESS)
 			break;
 
-		/* Sleep for a bit between tries.  This gives the 1-wire GPIO
+		/*
+		 * Sleep for a bit between tries.  This gives the 1-wire GPIO
 		 * chip time to recover from the failed attempt, and allows
-		 * lower-priority tasks a chance to run. */
+		 * lower-priority tasks a chance to run.
+		 */
 		usleep(100);
 	}
 
 	return rv;
 }
 
-
 /*****************************************************************************/
 /* Console commands */
 
diff --git a/include/onewire.h b/include/onewire.h
index f28abdd9b4..afa3a2f3d1 100644
--- a/include/onewire.h
+++ b/include/onewire.h
@@ -5,25 +5,39 @@
 
 /* 1-wire interface for Chrome EC */
 
-/* Note that 1-wire communication is VERY latency-sensitive.  If these
+/*
+ * Note that 1-wire communication is VERY latency-sensitive.  If these
  * functions are run at low priority, communication may be garbled.  However,
  * these functions are also slow enough (~1ms per call) that it's really not
  * desirable to put them at high priority.  So make sure you check the
  * confirmation code from the slave for any communication, and retry a few
- * times in case of failure. */
+ * times in case of failure.
+ */
 
 #ifndef __CROS_EC_ONEWIRE_H
 #define __CROS_EC_ONEWIRE_H
 
 #include "common.h"
 
-/* Reset the 1-wire bus.  Returns error if presence detect fails. */
+/**
+ * Reset the 1-wire bus.
+ *
+ * @return EC_SUCCESS, or non-zero if presence detect fails.
+ */
 int onewire_reset(void);
 
-/* Read a byte from the 1-wire bus.  Returns the byte. */
+/**
+ * Read a byte from the 1-wire bus.
+ *
+ * @return The byte value read.
+ */
 int onewire_read(void);
 
-/* Write a byte to the 1-wire bus. */
+/**
+ * Write a byte to the 1-wire bus.
+ *
+ * @param data		Byte to write
+ */
 void onewire_write(int data);
 
 #endif  /* __CROS_EC_ONEWIRE_H */
diff --git a/include/power_led.h b/include/power_led.h
index ccee086f70..2fd7322095 100644
--- a/include/power_led.h
+++ b/include/power_led.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2011 The Chromium OS Authors. All rights reserved.
+/* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
@@ -10,6 +10,8 @@
 
 #include "common.h"
 
+/* Interface for LM4-based boards */
+
 enum powerled_color {
 	POWERLED_OFF = 0,
 	POWERLED_RED,
@@ -18,6 +20,25 @@ enum powerled_color {
 	POWERLED_COLOR_COUNT  /* Number of colors, not a color itself */
 };
 
+#ifdef CONFIG_POWER_LED
+
+/**
+ * Set the power adapter LED
+ *
+ * @param color		Color to set LED
+ *
+ * @return EC_SUCCESS, or non-zero if error.
+ */
+int powerled_set(enum powerled_color color);
+
+#else
+
+static inline int powerled_set(enum powerled_color color) { return 0; }
+
+#endif
+
+/* Interface for STM32-based boards */
+
 enum powerled_state {
 	POWERLED_STATE_OFF,
 	POWERLED_STATE_ON,
@@ -31,16 +52,19 @@ enum powerled_config {
 	POWERLED_CONFIG_PWM,
 };
 
-#if defined(CONFIG_TASK_POWERLED) || defined(CONFIG_POWER_LED)
-/* Set the power adapter LED to the specified color. */
-int powerled_set(enum powerled_color color);
+#ifdef CONFIG_TASK_POWERLED
 
-/* Set the power LED according to the specified state. */
+/**
+ * Set the power LED
+ *
+ * @param state		Target state
+ */
 void powerled_set_state(enum powerled_state state);
 
-#else  /* CONFIG_TASK_POWERLED */
-static inline int powerled_set(enum powerled_color color) { return 0; }
+#else
+
 static inline void powerled_set_state(enum powerled_state state) {}
-#endif /* CONFIG_TASK_POWERLED */
 
-#endif  /* __CROS_EC_POWER_LED_H */
+#endif
+
+#endif /* __CROS_EC_POWER_LED_H */