Add sendHint method to the PowerHintSession API for load changes

Add a new sendHint(SessionHint hint) method to the PowerHintSession to
allow clients to inform the session about upcoming changes in load ahead
of time.

Bug: b/243973548
Test: atest VtsHalPowerTargetTest
Change-Id: I0a8af42d3b0ccd3bbb72287a9b91ffb13fccaf9c

compatibility_matrices/compatibility_matrix.current.xml

@@ -432,7 +432,7 @@
     </hal>
     <hal format="aidl" optional="false">
         <name>android.hardware.power</name>
-        <version>2-3</version>
+        <version>2-4</version>
         <interface>
             <name>IPower</name>
             <instance>default</instance>

power/aidl/aidl_api/android.hardware.power/current/android/hardware/power/IPowerHintSession.aidl

@@ -39,4 +39,5 @@ interface IPowerHintSession {
   oneway void pause();
   oneway void resume();
   oneway void close();
+  oneway void sendHint(android.hardware.power.SessionHint hint);
 }

power/aidl/aidl_api/android.hardware.power/current/android/hardware/power/SessionHint.aidl

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2022 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+///////////////////////////////////////////////////////////////////////////////
+// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE.                          //
+///////////////////////////////////////////////////////////////////////////////
+
+// This file is a snapshot of an AIDL file. Do not edit it manually. There are
+// two cases:
+// 1). this is a frozen version file - do not edit this in any case.
+// 2). this is a 'current' file. If you make a backwards compatible change to
+//     the interface (from the latest frozen version), the build system will
+//     prompt you to update this file with `m <name>-update-api`.
+//
+// You must not make a backward incompatible change to any AIDL file built
+// with the aidl_interface module type with versions property set. The module
+// type is used to build AIDL files in a way that they can be used across
+// independently updatable components of the system. If a device is shipped
+// with such a backward incompatible change, it has a high risk of breaking
+// later when a module using the interface is updated, e.g., Mainline modules.
+
+package android.hardware.power;
+@Backing(type="int") @VintfStability
+enum SessionHint {
+  CPU_LOAD_UP = 0,
+  CPU_LOAD_DOWN = 1,
+  CPU_LOAD_RESET = 2,
+  CPU_LOAD_RESUME = 3,
+}

power/aidl/android/hardware/power/IPowerHintSession.aidl

@@ -16,6 +16,7 @@
 
 package android.hardware.power;
 
+import android.hardware.power.SessionHint;
 import android.hardware.power.WorkDuration;
 
 @VintfStability
@@ -56,4 +57,12 @@ oneway interface IPowerHintSession {
      * Close the session to release resources.
      */
     void close();
+
+    /**
+     * Gives information to the PowerHintSession about upcoming or unexpected
+     * changes in load to supplement the normal updateTarget/reportActual cycle.
+     *
+     * @param hint The hint to provide to the PowerHintSession
+     */
+    void sendHint(SessionHint hint);
 }

power/aidl/android/hardware/power/SessionHint.aidl

@@ -0,0 +1,46 @@
+/*
+ * Copyright (C) 2022 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.power;
+
+@VintfStability
+@Backing(type="int")
+enum SessionHint {
+    /**
+     * This hint indicates an increase in CPU workload intensity. It means that
+     * this hint session needs extra CPU resources to meet the target duration.
+     * This hint must be sent before reporting the actual duration to the session.
+     */
+    CPU_LOAD_UP = 0,
+    /**
+     * This hint indicates a decrease in CPU workload intensity. It means that
+     * this hint session can reduce CPU resources and still meet the target duration.
+     */
+    CPU_LOAD_DOWN = 1,
+    /*
+     * This hint indicates an upcoming CPU workload that is completely changed and
+     * unknown. It means that the hint session should reset CPU resources to a known
+     * baseline to prepare for an arbitrary load, and must wake up if inactive.
+     */
+    CPU_LOAD_RESET = 2,
+    /*
+     * This hint indicates that the most recent CPU workload is resuming after a
+     * period of inactivity. It means that the hint session should allocate similar
+     * CPU resources to what was used previously, and must wake up if inactive.
+     */
+    CPU_LOAD_RESUME = 3,
+
+}

power/aidl/default/Android.bp

@@ -30,7 +30,7 @@ cc_binary {
     shared_libs: [
         "libbase",
         "libbinder_ndk",
-        "android.hardware.power-V3-ndk",
+        "android.hardware.power-V4-ndk",
     ],
     srcs: [
         "main.cpp",

power/aidl/default/power-default.xml

@@ -1,7 +1,7 @@
 <manifest version="1.0" type="device">
     <hal format="aidl">
         <name>android.hardware.power</name>
-        <version>3</version>
+        <version>4</version>
         <fqname>IPower/default</fqname>
     </hal>
 </manifest>

power/aidl/vts/Android.bp

@@ -32,7 +32,7 @@ cc_test {
         "libbinder_ndk",
     ],
     static_libs: [
-        "android.hardware.power-V3-ndk",
+        "android.hardware.power-V4-ndk",
     ],
     test_suites: [
         "vts",

power/aidl/vts/VtsHalPowerTargetTest.cpp

@@ -34,12 +34,16 @@ using android::hardware::power::Boost;
 using android::hardware::power::IPower;
 using android::hardware::power::IPowerHintSession;
 using android::hardware::power::Mode;
+using android::hardware::power::SessionHint;
 using android::hardware::power::WorkDuration;
 
 const std::vector<Boost> kBoosts{ndk::enum_range<Boost>().begin(), ndk::enum_range<Boost>().end()};
 
 const std::vector<Mode> kModes{ndk::enum_range<Mode>().begin(), ndk::enum_range<Mode>().end()};
 
+const std::vector<SessionHint> kSessionHints{ndk::enum_range<SessionHint>().begin(),
+                                             ndk::enum_range<SessionHint>().end()};
+
 const std::vector<Boost> kInvalidBoosts = {
         static_cast<Boost>(static_cast<int32_t>(kBoosts.front()) - 1),
         static_cast<Boost>(static_cast<int32_t>(kBoosts.back()) + 1),
@@ -50,6 +54,11 @@ const std::vector<Mode> kInvalidModes = {
         static_cast<Mode>(static_cast<int32_t>(kModes.back()) + 1),
 };
 
+const std::vector<SessionHint> kInvalidSessionHints = {
+        static_cast<SessionHint>(static_cast<int32_t>(kSessionHints.front()) - 1),
+        static_cast<SessionHint>(static_cast<int32_t>(kSessionHints.back()) + 1),
+};
+
 class DurationWrapper : public WorkDuration {
   public:
     DurationWrapper(int64_t dur, int64_t time) {
@@ -175,6 +184,7 @@ TEST_P(PowerAidl, createAndCloseHintSession) {
     ASSERT_TRUE(session->close().isOk());
     session.reset();
 }
+
 TEST_P(PowerAidl, createHintSessionFailed) {
     std::shared_ptr<IPowerHintSession> session;
     auto status = power->createHintSession(getpid(), getuid(), kEmptyTids, 16666666L, &session);
@@ -198,6 +208,21 @@ TEST_P(PowerAidl, updateAndReportDurations) {
     ASSERT_TRUE(session->reportActualWorkDuration(kDurations).isOk());
 }
 
+TEST_P(PowerAidl, sendSessionHint) {
+    std::shared_ptr<IPowerHintSession> session;
+    auto status = power->createHintSession(getpid(), getuid(), kSelfTids, 16666666L, &session);
+    if (!status.isOk()) {
+        EXPECT_TRUE(isUnknownOrUnsupported(status));
+        return;
+    }
+    for (const auto& sessionHint : kSessionHints) {
+        ASSERT_TRUE(session->sendHint(sessionHint).isOk());
+    }
+    for (const auto& sessionHint : kInvalidSessionHints) {
+        ASSERT_TRUE(session->sendHint(sessionHint).isOk());
+    }
+}
+
 // FIXED_PERFORMANCE mode is required for all devices which ship on Android 11
 // or later
 TEST_P(PowerAidl, hasFixedPerformance) {