cr50: Clean up device state code

This mostly adds a bunch of comments, but does make a few changes to
the code:

1) The devices console command now prints both the current device
state and the last known state.

2) servo_state_unknown() also checks if we're bit-banging the EC UART,
since that could also cause EC_DETECT to go high.

BUG=none
BRANCH=cr50
TEST=make buildall; use 'devices' command

Change-Id: I73e7524545ef49494eb36155b99f4042c1fd466d
Signed-off-by: Randall Spangler <rspangler@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/602695
Reviewed-by: Mary Ruthven <mruthven@chromium.org>
(cherry picked from commit 6c55126080f7fa1f165d38924834c894c4a24c27)
Reviewed-on: https://chromium-review.googlesource.com/622267
Commit-Queue: Vadim Bendebury <vbendeb@chromium.org>
Tested-by: Vadim Bendebury <vbendeb@chromium.org>
Reviewed-by: Vadim Bendebury <vbendeb@chromium.org>

1 files changed, 63 insertions, 14 deletions

diff --git a/include/device_state.h b/include/device_state.h
index 372b59cb75..7d22846d9e 100644
--- a/include/device_state.h
+++ b/include/device_state.h
@@ -3,8 +3,6 @@
  * found in the LICENSE file.
  */
 
-#include "gpio.h"
-
 #ifndef __CROS_DEVICE_STATE_H
 #define __CROS_DEVICE_STATE_H
 
@@ -16,31 +14,82 @@ enum device_state {
 	DEVICE_STATE_COUNT,
 };
 
+enum gpio_signal;
+
+/* Device configuration */
 struct device_config {
-	const char *name;		/* Device name */
-	enum device_state state;	/* Device status */
-	enum device_state last_known_state;	/* Either off or on */
-	/* Deferred handler to detect power off */
+	/* Device name */
+	const char *name;
+
+	/* Current state */
+	enum device_state state;
+
+	/*
+	 * Last known state.  That is, the last state value passed to
+	 * device_set_state() which was DEVICE_STATE_OFF or DEVICE_STATE_ON.
+	 * Or DEVICE_STATE_UNKNOWN, if device_set_state() has not been called
+	 * for this device this boot.
+	 */
+	enum device_state last_known_state;
+
+	/*
+	 * Deferred handler to debounce state transitions. This is NOT used by
+	 * the device_state module; it's just here as a convenience for the
+	 * board.
+	 */
 	const struct deferred_data *deferred;
-	enum gpio_signal detect;	/* GPIO detecting power on */
+
+	/*
+	 * GPIO used to detect the state.  This is NOT used by the device_state
+	 * module; it's just here as a convenience for the board.
+	 */
+	enum gpio_signal detect;
 };
 
+/*
+ * board.h must supply an enumerated list of devices, ending in DEVICE_COUNT.
+ */
 enum device_type;
 
+/*
+ * board.c must provide this list of device configurations.  It must match enum
+ * device_type, and must be DEVICE_COUNT entries long.
+ */
 extern struct device_config device_states[];
 
-/* Return the device state */
-int device_get_state(enum device_type device);
+/**
+ * Get the current state for the device.
+ *
+ * @param device	Device to check
+ * @return The device state (current; NOT last known).
+ */
+enum device_state device_get_state(enum device_type device);
 
 /**
- * Sets the device state
+ * Set the device state
+ *
+ * Updates the device's last known state if <state> is DEVICE_STATE_ON or
+ * DEVICE_STATE_OFF, and that's different than the device's last known state.
  *
- * @param device	the device to update
- * @param state		the new device state
- * @return true if the last_known_state was changed
+ * Note that this only changes the recorded state.  It does not notify anything
+ * of these changes.  That must be done by the caller.
+ *
+ * @param device	Device to update
+ * @param state		New device state
+ * @return non-zero if this changed the device's last known state.
  */
 int device_set_state(enum device_type device, enum device_state state);
 
-/* Update the device state based on the device gpios */
+/**
+ * Update the device state based on the device gpios.
+ *
+ * The board must implement this.  It will be called for each device in the
+ * context of HOOK_SECOND.  If the state has changed, the board is responsible
+ * for doing any associated reconfiguration and then calling
+ * device_set_state().
+ *
+ * @param device	Device to check.
+ */
 void board_update_device_state(enum device_type device);
+
 #endif  /* __CROS_DEVICE_STATE_H */