Address the IThermal HAL API feedback
Explained why thresholds could change and how to handle it.
Bug: 360486877
Test: n/a
Flag: EXEMPT hal
Change-Id: I82037e45a237d2a850caed681efd9e0086e7b9ba
diff --git a/thermal/aidl/android/hardware/thermal/IThermal.aidl b/thermal/aidl/android/hardware/thermal/IThermal.aidl
index 87f7637..7c0ee24 100644
--- a/thermal/aidl/android/hardware/thermal/IThermal.aidl
+++ b/thermal/aidl/android/hardware/thermal/IThermal.aidl
@@ -227,12 +227,12 @@
void unregisterCoolingDeviceChangedCallback(in ICoolingDeviceChangedCallback callback);
/**
- * Retrieves the forecasted skin temperature in Celsius.
+ * Retrieves the forecasted {@link TemperatureType#SKIN} type temperature in Celsius.
*
* @param forecastSeconds the number of seconds to forecast the skin temperature, it should
- * at least support superset of [0, 60] seconds range.
+ * support any value from a superset of range [0, 60] seconds.
*
- * @return forecasted skin temperature in Celsius.
+ * @return forecasted skin temperature in Celsius unit at the forecasted seconds in future.
*
* @throws EX_ILLEGAL_STATE If the Thermal HAL is not initialized successfully
* @throws EX_ILLEGAL_ARGUMENT If the provided forecastSeconds is negative
diff --git a/thermal/aidl/android/hardware/thermal/IThermalChangedCallback.aidl b/thermal/aidl/android/hardware/thermal/IThermalChangedCallback.aidl
index 1ff4b7a..b40b7c2 100644
--- a/thermal/aidl/android/hardware/thermal/IThermalChangedCallback.aidl
+++ b/thermal/aidl/android/hardware/thermal/IThermalChangedCallback.aidl
@@ -26,8 +26,7 @@
@VintfStability
interface IThermalChangedCallback {
/**
- * Send a thermal throttling event to all Thermal HAL
- * thermal event listeners.
+ * Send a thermal throttling event to all Thermal HAL thermal event listeners.
*
* @param temperature The temperature associated with the
* throttling event.
@@ -35,8 +34,14 @@
oneway void notifyThrottling(in Temperature temperature);
/**
- * Send a thermal threshold change event to all Thermal HAL
- * thermal event listeners.
+ * Send a thermal threshold change event to all Thermal HAL thermal event listeners.
+ *
+ * Some devices may change the thresholds based on hardware state or app workload changes.
+ * While this is generally not recommended, it should be used with caution at low frequency
+ * especially for the {@link TemperatureType#SKIN} type temperature thresholds. Since such
+ * a skin type callback to system may trigger notifications to apps that have preivously
+ * registered thermal headroom listeners with a new set of headroom and thresholds in case
+ * any of them changed.
*
* @param threshold The temperature threshold that changed.
*/