1 files changed, 61 insertions, 26 deletions

diff --git a/include/device_state.h b/include/device_state.h
index d7ff0661dc..e7894ba998 100644
--- a/include/device_state.h
+++ b/include/device_state.h
@@ -3,50 +3,85 @@
  * found in the LICENSE file.
  */
 
-#include "gpio.h"
-
 #ifndef __CROS_DEVICE_STATE_H
 #define __CROS_DEVICE_STATE_H
 
-/* Device state indexes */
-enum device_state {
-	DEVICE_STATE_UNKNOWN = 0,
-	DEVICE_STATE_OFF,
-	DEVICE_STATE_ON,
-	DEVICE_STATE_COUNT,
-};
+enum gpio_signal;
 
+/* Device configuration */
 struct device_config {
-	const char *name;		/* Device name */
-	enum device_state state;	/* Device status */
-	/* 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_on;	/* GPIO detecting power on */
-	enum gpio_signal detect_off;	/* GPIO detecting power off */
+
+	/*
+	 * 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);
-
 /**
- * Sets the device state
+ * Get the current state for the device.
  *
- * @param device	the device to update
- * @param state		the new device state
+ * @param device	Device to check
+ * @return The device state (current; NOT last known).
  */
-void device_set_state(enum device_type device, enum device_state state);
+enum device_state device_get_state(enum device_type device);
 
-/* Update the device state based on the device gpios */
-void board_update_device_state(enum device_type device);
+/**
+ * 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.
+ *
+ * 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);
 
 /**
- * Enables or disables all device gpio interrupts
+ * 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 enable	enable or disable detection
+ * @param device	Device to check.
  */
-void device_detect_state_enable(int enable);
+void board_update_device_state(enum device_type device);
+
 #endif  /* __CROS_DEVICE_STATE_H */