Add new HWC_POWER_MODE_DOZE_SUSPEND power state.

Change-Id: Ice194315bc51ca25732c9e30c809bd6b39f3718f

include/hardware/hwcomposer.h

@@ -619,12 +619,8 @@ typedef struct hwc_composer_device_1 {
          * setPowerMode(..., mode)
          * Sets the display screen's power state.
          *
-         * The expected functionality for the various modes is as follows:
+         * Refer to the documentation of the HWC_POWER_MODE_* constants
-         * HWC_POWER_MODE_OFF    : Turn the display off.
+         * for information about each power mode.
-         * HWC_POWER_MODE_DOZE   : Turn on the display (if it was previously
-         *                         off) and put the display in a low power mode.
-         * HWC_POWER_MODE_NORMAL : Turn on the display (if it was previously
-         *                         off), and take it out of low power mode.
          *
          * The functionality is similar to the blank() command in previous
          * versions of HWC, but with support for more power states.

include/hardware/hwcomposer_defs.h

@@ -201,9 +201,28 @@ enum {
 
 /* Display power modes */
 enum {
+    /* The display is turned off (blanked). */
     HWC_POWER_MODE_OFF      = 0,
+    /* The display is turned on and configured in a low power state
+     * that is suitable for presenting ambient information to the user,
+     * possibly with lower fidelity than normal but greater efficiency. */
     HWC_POWER_MODE_DOZE     = 1,
+    /* The display is turned on normally. */
     HWC_POWER_MODE_NORMAL   = 2,
+    /* The display is configured as in HWC_POWER_MODE_DOZE but may
+     * stop applying frame buffer updates from the graphics subsystem.
+     * This power mode is effectively a hint from the doze dream to
+     * tell the hardware that it is done drawing to the display for the
+     * time being and that the display should remain on in a low power
+     * state and continue showing its current contents indefinitely
+     * until the mode changes.
+     *
+     * This mode may also be used as a signal to enable hardware-based doze
+     * functionality.  In this case, the doze dream is effectively
+     * indicating that the hardware is free to take over the display
+     * and manage it autonomously to implement low power always-on display
+     * functionality. */
+    HWC_POWER_MODE_DOZE_SUSPEND  = 3,
 };
 
 /*****************************************************************************/