From 2ee5363ba989ea396369039fc00e66021d1eb37c Mon Sep 17 00:00:00 2001
From: Nathalie Le Clair <lcnathalie@google.com>
Date: Mon, 15 Mar 2021 18:00:01 +0100
Subject: [PATCH] Document intents triggering CEC power control messages

Specific to Android TV playback devices sending power control messages
to the HDMI-connected TV.

Bug: 170097638
Test: make
Change-Id: I97907d9d6a4522425306ad2cc9d10aef1f4c8869
---
 core/java/android/os/PowerManager.java | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/core/java/android/os/PowerManager.java b/core/java/android/os/PowerManager.java
index e5163d83de699..42064d3e596d0 100644
--- a/core/java/android/os/PowerManager.java
+++ b/core/java/android/os/PowerManager.java
@@ -197,6 +197,9 @@ public final class PowerManager {
      * application as the normal behavior.  Notifications that pop up and want
      * the device to be on are the exception; use this flag to be like them.
      * </p><p>
+     * Android TV playback devices attempt to turn on the HDMI-connected TV via HDMI-CEC on any
+     * wake-up, including wake-ups triggered by wake locks.
+     * </p><p>
      * Cannot be used with {@link #PARTIAL_WAKE_LOCK}.
      * </p>
      */
@@ -1292,6 +1295,9 @@ public final class PowerManager {
      * device will be put to sleep. If the {@link com.android.server.display.DisplayGroup#DEFAULT
      * default display group} is already off then nothing will happen.
      *
+     * <p>If the device is an Android TV playback device and the current active source on the
+     * HDMI-connected TV, it will attempt to turn off that TV via HDMI-CEC.
+     *
      * <p>
      * Overrides all the wake locks that are held.
      * This is what happens when the power key is pressed to turn off the screen.
@@ -1423,6 +1429,10 @@ public final class PowerManager {
      * be turned on. Additionally, if the device is asleep it will be awoken. If the {@link
      * android.view.Display#DEFAULT_DISPLAY default display} is already on then nothing will happen.
      *
+     * <p>If the device is an Android TV playback device, it will attempt to turn on the
+     * HDMI-connected TV and become the current active source via the HDMI-CEC One Touch Play
+     * feature.
+     *
      * <p>
      * This is what happens when the power key is pressed to turn on the screen.
      * </p><p>